Generate special code for rustdoc compilations

[Robbepop]

Currently the auto generated documentation for smart contracts written in the eDSL (pdsl_lang) is sup optimal. For example messages have their env: &EnvHandler argument that should not be visible in the documentation.

Using rust-lang/rust#43781 we can get further with conditional compilation.
So upon using pdsl_lang we can catch a rustfmt or cargo fmt run with #[cfg(rustdoc)] and can generate special code just for documentation purposes.

[Robbepop]

We want to make use of this Rust feature in order to generate special code upon rustfmt compilation. In the end we want clear and concise docs for our smart contracts.

Example

If we take the simple example Flipper smart contract we want to generate code in rustfmt mode as if our code was actually just the following:

/// The flipper contracts that can flip its value and return its current state.
struct Flipper {
    /// Our to-be-flipped value.
    value: storage::Value<bool>,
}

impl Flipper {
    /// Flips the state of the value.
    pub fn flip(&mut self) {
        if *self.value {
            *self.value = false;
        } else {
            *self.value = true;
        }
    }

    /// Returns the current state of the value.
    pub fn get(&self) {
        *self.value
    }
}

Note

Since we want to support source code inspection we also need to generate all private functions and need to implement the only-doc generated functions like they are supposed to be.

However, for the sake of simplicity we do not require the generated code to be syntactically correct since it might be using env without source (no longer appears in the parameters). Fortunately rustfmt doesn't require the documented source to be valid.

[Robbepop]

Superseeded by newer #336.