Is there an option or a method to allow documentation comments (starting with ##) to precede the thing being commented, rather than inside it?
Something like:
## This type contains a description of a person
type Person* = object
name: string
age: int
rather than:
type Person* = object
## This type contains a description of a person
name: string
age: int
TIA,
Stu
I asked the same some years ago for procs.
Indeed I like to have the whole proc code as short as possible, fitting on the screen as a whole, so comments between proc header and proc body is not that nice.
Araq told me that proc comment is a part of the proc, so place should be after proc header which makes some sense.
But while developing I put all comment before header.
Another recent idea of me is handling longer comments like footnotes in papers, so maybe having only a tag like "#myFineProc007" near the proc header, and the real text at the bottom of the file. But I have not yet tested that idea.
We're probably in the realm if personal taste here but I find:
comment
comment
comment
code
code
code
easier to scan and read than:
code
comment
comment
comment
code
code
I find the proc signature is the fine print and the comment block before it the motivating and background text. However, it's a personal preference so I'll go with the community standard.
While I'm asking questions about documentation comments, can I confirm that for a single line const declaration like:
const Answer* = 42 ## doc comment here
The documentation comment must be on the same line as the declaration, and not one of these?
## doc comment here
const Answer* = 42
or
const Answer* = 42
## doc comment here
both these work:
const Answer1* = 42
## doc comment here
const Answer2* = 42 ## doc comment here
if you can't find this in docs, please make a PR