Well, the way docs are implemented right now is that the parser shoehorns doc
comments into somewhat random locations in the AST and gives this to `nim doc`,
but there isn't a comprehensive set of rules for what comment belongs to which
item:
proc f(
arg: int, ## Is this a comment that belongs to arg?
## What about this one? Or does it belong to arg2
arg2: int,
## What about this one? and why does it need a comma above?
)
type X = object
## Is this a comment about X or the field that follows?
field: int
Run
The parser is full of little quirks like that which would benefit from a
simple-to-remember rule, such as "require indent for doc comments, attach them
to the less indented thing".
proc f(
arg1: int
## Indented and belongs to "previous thing"
arg2: int
)
Run
Unfortunately, it looks like the parser / grammar for doc comments was built ..
incrementally .. so there are many conventions in the current parser, many of
them arbitrary / unstructured.
One option is indeed to go the javadoc way of repeating everything in the doc
comment but I'd prefer an approach where the grammar and parsers are reviewed
to increase the regularity of where doc comments may appear and how they
"attach" to a specific element such that we avoid needless repetition while
maintaining syntactic simplicity (such as reusing the "ideas" of indent
representing structural relationships).
