RFC: Comments, Docs and Headers

[Qix-]

Arua provides three types of comments: # for general comments, #: for documentation comments, and ## for header comments.

All comments must start with one of the three variations above, with no spaces between them, and extend to the end of the line (\n).

---

#

The singular # prefix is used for all generic comments, notes, explanations, and other remarks regarding any piece of code.

These comments are ignored completely. The parser may choose to skip to the next line upon encountering a # <space>.

Generic comments do not affect ordering requirements.

#:

The #: prefix is a documentation comment, and must come directly before a member declaration.

These comments can contain one or more docstring tags.

#: This is the main entry point
#: param args: The arguments passed to the application from the command line
#: return: An exit code, where 0 indicates success and all other numbers indicate failure
fn main(args [str]) i32
    ret 0

There are a few special docstring tags used by the Arua compiler to assist in debugging or error messages.

• param <name>: - documents a parameter's intended use
• return [val[, ...]]: - documents the meaning of the return value(s) (see below for explanation)

Docstring tags must be alphanumeric.

Any tag can have associated values, separated by commas, that should be treated as 'conditional' or 'identifying' strings to supplement the intended meaning of the tag itself.

return: tags may provide values that indicate what an exceptional return value means. This is useful in cases of "If X then this action occurred; otherwise, another action occurred."

For example, in the case of a theoretical .get() method that could return nil if the key doesn't exist or the value itself if the key does exist, the return docstring might look like:

#: return: The value associated with the key
#: return nil: The key could not be found

Docstring tags are unique based on their tag name and any associated value, including the lack of value. This means that param A: and param B: are unique to each other and thus can coexist in the same documentation comment.

Non-unique docstring tags are not allowed.

##

The double ## prefix indicates a header comment. These comments are used to discern things such as licenses, contact points, etc.

Header comments must come before any statement in the file.

Similar to documentation comments, header comments may contain tags that describe the content of the module. Refer to documentation comments regarding the format of tags.

These are the special header comment tag(s):

• license: - a SPDX identifier that pertains to a license, or proprietary for proprietary software with custom or non-open-source licenses. In the event of the latter, it should be expected that a license is provided within the header or the associated repository, though this isn't enforced by Arua.

Header comments are intended to be used primarily by license validation tools, IDEs (to either hide or display differently the header comment), or by formatting utilities to ease the pain of determining what's a header and what is file-specific documentation.

[corbin-r]

For comments, I think having # as generic comments, ## as commentdocs, and ### and headers and copyrights is a good idea.
This could also be collapsed into #17 as an imposed style for writing Arua? Or will it be parsed as an actual thing into the compiler and possibly spit out formatted documentation.. Kind of like a built in Doxygen?

[Qix-]

Similar to Python/Java where ## can be referenced as a documentation symbol.

[corbin-r]

Gotcha. That works. So it's more a styling thing rather than an actual functionality.

[Qix-]

Instead of #, ## and ### I'm choosing #, #: and ## instead. Here's why:

• # - nothing changed, it's standard and everyone uses this
• #: - faster to type than ## and much easier on the eyes when they grow large
• ## - seems bolder, and conveys more 'pushy' comments without having a needless third character.