Syntax to distinguish documentation from comments

[zimbatm]

It's related to #5

Some languages make the distinction between comments and documentation block by extending the comment syntax. For example in Rust, // is a comment and /// is documentation. It has the nice property of being backward-compatible.

Nix could be extended in a similar way. It could even allow to select the content type of the doc block. Eg:

/**md
# My title
My body
*/

Or (pure text on single line)

/// This is my single-line doc

This would also be an advantage for tooling like nixdoc that have to make the distinction between comments and documentation as it would make the heuristics simpler.

If you think that this is a good idea, let's propose this by using a RFC

[infinisil]

This is now an RFC!

[infinisil]

The RFC has been accepted and is now implemented in nixdoc :)