implement forc doc

[leviathanbeak]

it should generate docs for Sway constructs: Structs, Enums, Traits, Functions etc
it should work similar as cargo doc

[emilyaherbert]

Is this unblocked by #267?

[leviathanbeak]

@emilyaherbert it definitely helps a lot, thanks!

[mitchmindtree]

Just updating this with some recent developments:

Sway now supports attributes as of #1488. The easiest approach to implementing this might be to follow in Rust's footsteps by supporting doc comments on Items by desugaring them to #[doc = "String of documentation"].

Implementation

Might look something like:

1. Add support for doc attributes, i.e. #[doc = "blah blah blah"] or #[doc("blah blah blah")]. This might involve adding support for string literals in attributes.
2. Update the sway-parse to desugar doc comments on Items /// blah blah to attributes #[doc("blah blah")].
3. Add a sway-doc crate that:
   1. Parses a project.
   2. Traverses the ParseProgram and collects a map of module paths to their associated doc comments.
   3. Uses the map of module paths to doc strings to generate HTML. 🪄
4. Add a forc doc CLI command that calls into the sway-doc implementation.

Step 3 and its parts are a little hand-wavey for now and gloss over big steps like linking Item declarations, nesting example code, and so on.

That said, it's probably best to start by getting some basic, raw HTML+markdown docs with minimal (no) linking working first, then we can write up dedicated issues for fancier features like styling, linking to other item declarations (perhaps using TypedProgram rather than ParseProgram), and so on.

[nfurfaro]

We will also need to consider how to handle our current multiline docs, i.e:

/// Withdraw coins back to L1 and burn the corresponding amount of coins
/// on L2.
///
/// # Arguments
///
/// * `to` - the destination of the transfer (an Address or a ContractId)
///
/// # Reverts
///   
/// * When no coins were sent with call

though rust probably already has a solution for this too.

[mitchmindtree]

My intuition is that multiline doc comments are handled just the same, but the attribute they turn into is broken along multiple lines, something like:

#[doc = r###"
Withdraw coins back to L1 and burn the corresponding amount of coins on L2.

# Arguments

* `to` - the destination of the transfer (an Address or a ContractId)

# Reverts
   
* When no coins were sent with call
"###]

[otrho]

1. Add support for doc attributes, i.e. #[doc = "blah blah blah"] or #[doc("blah blah blah")]. This might involve adding support for string literals in attributes.

Do we actually want to support this syntax? Right now an attribute is an Ident and an optional list of Ident args. If we just parse /// comments into the main Ident then nothing else needs to be done. Idents can have newlines, they're just a wrapper around a span. The only trickiness is removing the /// from the start of each line.

[mitchmindtree]

For future readers/implementers: this RFC covers the parsing of doc comments into an attribute representation, a good first step in addressing this.

@sezna I think I remember you mentioning you'd started on this^ ? If so, are you up for posting a draft?

Now that sway-fmt-v2 is just about ready, I'm thinking forc doc could be a good next candidate and just want to check if there's any behind-the-scenes progress we should be aware of before we dive in :)

[sezna]

I have not started on any actual implementation of docstrings. That task is still open for the taking. I just went ahead and cleared assignees: #149