Comments and Doc Comments Syntax

[ozra]

-- here's a comment
say "ok!" -- and here

--| This function blows up this universe!
--| Will be better documented after Ragnarök
some-func(x Int) -> x / 0

-- _[ed: added 17-04-05]:_

--/ A Multi Line Doc Comment
    that ends when
    dedent is reached
some-func(x --[an inline comment here]-- Int) -> x

--\ Or Maybe Backslash
    or maybe both, that
       could work
    too

Prior Art

• -- and additional variations are used by Ada, Eiffel, Haskell, Lua, SQL, etc..
• // is a more awkward form (albeit very familiar to most of us). I suspect it was chosen back in the days to allow -- decrement operator without additional contextual rules for syntax. In Onyx you write x -= 1 for that (deliberately not allowing inc/dec op; it's not a "side effect").
• # is a very good symbol to have in syntax, wasting it on comments isn't preferred! It is currently used as prefix for Tag-values (aka "Symbols" in Crystal and Ruby) and in some hash / key-value scenarios for sugar-constructs. It's otherwise pretty universal in the different doc-syntaxes where it's used in; and only one char — good points for it. But, still, it doesn't have a "natural" (typographic / writing rules) reason for it.

Propositions

1. -- and (--| or --:) (double hyphens only) for comments and doc comments
2. As per above an also: — and (—| or —:) (EMDASH [\u2014]) interchangeably for comments and doc comments respectively
3. [ed: added 17-04-05]: Different forms of symmetric and multiline comments also: --[ comment ]--, --/ begin comments that close with dedent, etc.
   • Also here it is probably good to designate classes of intent to different comment-markers: simply code put out of action, dev-to-dev comment on impl-details, etc. vs. officially documenting comments (for doc-extraction).

Motivation

• The reason I chose the notation, before realizing a horde of languages had it, was because that's how I write comments in pseudo code on paper (well more of an EMDASH that is).
• The pipe | was then picked up from Haskell to specifically point out doc comments - discriminating between them is good. The : is a candidate for doc comment usage also.
• [ed: added 17-04-05]: finding a new editor (https://github.com/howl-editor/howl - highly recommended!!!) I came into contact with Lua and Moonscript. I think Lua's symmetric comment syntax (--[ comment ]--) would be good to steal from. This would be for "regular" commenting. In addition '--\', or '--/' for starting an indent-based multi line comment (ends on dedent), which is considered "eligible for documentation generation".

Allowing EMDASH (—, \u2014) could be nice. It looks more like natural writing and stands out a bit. Getting unicode into a de facto position is desirable, but relying on it is still a bit of fringe work.

Allowing them both makes it simple for those who:

• don't have EMDASH easily accessible on the keyboard (seems unlikely—it's a basic typographic feature), and
• can't easily configure it (xmodmap in linux, etc), or
• can't get their editor to replace -- with — upon typing, or
• simply just prefer double-hyphens.

Even though most of us prefer monotype while editing (hell, I know some people who prefer monotype for everything, even book reading!), EMDASH still looks a great deal wider than hyphen in most fonts, so it is clear (even without highlighting).

One downside is that it might not be available in all monotype fonts.

Style uniformity in a project is solved via formatter. Everyone should decide on a style and configure the formatter for it. One for checking in to project (project style), and one for personal editing. This way the project can have -- as mandatory style, while you use — during your editing sessions, if you prefer it.

NOTE

Currently the -- style is implemented. Distinction semantically between comments and doc comments is not decided by the notation yet, but currently by proximity.

[ed: added 17-04-05]: The suggestions above added with this edit/date marker are just ideas and not implemented yet.

[stugol]

Does the lack of # as a comment prefix cause a problem with shebang lines?

#!/usr/bin/onyx

[ozra]

There is a parsing exception allowing the shebang on the first line.

[stugol]

Neat.

[ozra]

Edited the OP and added multi-line / inline comment ideas.