Make contract docs visible to rustdoc

[cmichi]

Closes #336.

I need to make some of our example mod public, otherwise there will never be any documentation for the pub's in that module. We should also think about if we want to change the cargo contract new template and the workshops.

In terms of how it currently looks I uploaded the output of cargo doc --no-deps for two examples:

• flipper
• trait-erc20

I expect that we will need to discuss further details of what we want to hide/show in these docs, I created this PR also with the intention of starting this discussion and not with the idea of providing a perfect solution from the start. For example: Do we always want to hide __ink in the contract docs? Even if it's the event base?

[Robbepop]

Actually this is only part of the solution. We also (finally) need dedicated #[cfg(doc)] aware ink! codegen that produces code specially for generating documentation using cargo doc. E.g. ink! will produce different output if it notices that it is compiling for cargo doc.
Making the ink! module public is not the only solution. You could also publicly re-export all the important pub definitions on crate root and it is what I would actually prefer.

[cmichi]

Actually this is only part of the solution. We also (finally) need dedicated #[cfg(doc)] aware ink! codegen that produces code specially for generating documentation using cargo doc. E.g. ink! will produce different output if it notices that it is compiling for cargo doc.

@Robbepop Do you mean code which includes the doc-specific code under a feature flag? Because that's what I already do in this PR, e.g. here:

#[cfg(doc)]
const _: () = {
  use ::ink_lang::{Env, EmitEvent, StaticEnv};
};

#(
  #doc_item_impls
)*

[Robbepop]

The direction of this PR to solve the underlying issue is to implicitly expose the API of the smart contract to the outside thus enforcing pub ink! module.
Unfortunately this forces smart contract authors to have this constraint of a pub module.
What I'd like to see instead is to let the users decide what items and definitions they want to expose as with a normal Rust library or application and instead produce very clean and simple contract code with proper documentation everywhere when #[cfg(doc)] is enabled.
This requires yet another complete codegen for this case next to ink-as-dependency and std in the context of metadata and testing.

[cmichi]

Closed in favor of #632 as a follow-up.