Closed LPeter1997 closed 1 year ago
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.
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;
@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?
I agree that we could make summary optional. I'm neutral about params and parameters
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#
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:
cref
.see
,paramref
,typeparamref
, ... Damn it, let me just usesee
everywhere!Rust uses Markdown, which has many advantages, but also a few drawbacks:
# Arguments
section, and in there will be an enumeration of some sort.Many languages use javadoc-style tags:
<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.