[WIP] Documentation comments

[LPeter1997]

In my opinion a very unloved but important part of language design would be documentation comments. We read docs all day, we love good documentation but we usually dislike writing it. We could definitely help that a little in multiple ways.

Summary of the main styles

C# uses XML, which is horrific in multiple ways:

• Many relatively common programming symbols need to be escaped, making inserting example code really-really painful.
• The attribute names are really cryptic in places, like cref.
• There are way too many reference tags, like see, paramref, typeparamref, ... Damn it, let me just use see everywhere!
• I also don't think that anyone finds XML particularly easy to read or write.

Rust uses Markdown, which has many advantages, but also a few drawbacks:

• It's a relatively well-known format.
• It's an extremely flexible format, allows embedding code, almost arbitrary formatting capabilities.
• No need for separate documentation files, a module-level documentation can serve as the "module-showcase".
• It has simplified references.
• It lacks a bit of structure, that they solve by conventions and expect certain sections to contain certain kind of information. For example, argument documentation will be in an # Arguments section, and in there will be an enumeration of some sort.
• Since code snippets can be inserted, the compiler is even able to execute them, so there's automatic validation of sample code.

Many languages use javadoc-style tags:

• It's extremely lightweight and easy to read/write.
• There's a wide variety of existing tooling.
• Inserting example code is possible, but really annoying, as they are done with the <pre> HTML tag, bringing in the same escaping problem as with C# XML docs.

My thoughts

I think that XML definitely has to go. I really like the idea of not having to write extra documentation outside of my module, so I'm leaning towards the Rust-way, having full markdown support. But I think that the Rust format could be helped a bit with some convenience syntax. I don't think it would be a horrible thing to add javadoc tags to markdown.

Also executing code in comments is a really great way to not have outdated examples get left in the docs, I'm a fan of that.

Syntax

Since the current comment syntax is //, we could make doc comments something similar, like: ///, /!, ... Personally I'm fine with ///, but you can suggest a syntax in the comments.

[kfimchenko]

Have you seen golang comments? It looks easy to write and read. Also there is a tooling that generates static web site from source code with all documentation.
And linters that forces you to write documentation on public members.

[Binto86]

ok so here is some summary of what we came up with on discord server:
we would have markdown doc comments, with some small set of standard sections,:
summary
returns
params
exception
example
User could just use any custom section if he wants to
Some sections could be "expected" meaning the compiler would complain if they would be missing, these sections would be always summary, and other sections based on context e.g. returns if the documented symbol is method and returns something else than unit etc.
we could also make a flag in project file that would set severity of doc comments warnings for the "expected" parts of doc comment and for missing documentation on public members
section could just be marked with normal markdown #
params section would expect ither list like this:

# params
- a: what a is
- b: what b is

or subsection like:

#params
## a
what param a is.
## b
what param b is.

so doc comment for add function could look like this:

/// # summary
/// this function adds 2 ints
/// # returns
/// result of adition
/// #params
/// ## a
/// first number to add
/// ## b
/// second number to add
/// # Examples
/// `var added = add(5, 3) //8`
func add(a: int32, b: int32): int32 = a+b;

[svick]

@jakubbinter I like that approach, just a few small comments:

• I think the # Summary heading should be optional. In many cases, all that detailed documentation is an overkill and a single-line summary is sufficient. In those cases, it would be great if you could write just:

  /// this function adds 2 ints
  func add(a: int32, b: int32): int32 = a+b;
  

• I don't like that params is not the whole word, and would prefer Parameters instead. Or maybe both forms should be allowed?

[LPeter1997]

I agree that we could make summary optional. I'm neutral about params and parameters

[Binto86]

The names i proposed were the same as in c# because of convinience, it doesn't mean i want these names exactly, it means i would like sections that contain the same information as the proposed sections do in c#