Doc Comments and other documentation are important for a programming language. Many programming languages define a standard way for documentation for its ecosystem.
What should be the standard for Odin doc comments and other docs?
-
Rust uses CommonMark Markdown specification for doc comments, but added several extensions to CommonMark syntax.
Link: Rust Doc Comments -
Go-lang uses custom format and this has led to some problems.
Link: Go-lang Doc Comments - Common mistakes and pitfalls
Markdown is used in many places because it is very popular.
But the problem with Markdown is that different projects like Rust docs add extensions because Markdown lacks some basic features.
There are several alternatives to Markdown.
One such alternative is AsciiDoc.
Link: AsciiDoc
AsciiDoc
Features of AsciiDoc:
-
Simple and similar syntax like Markdown.
-
More powerful than Markdown.
-
Created to be featureful without using HTML tags.
-
Used to write Articles, Books, Unix Manpages, Slides, README, Doc Sites, etc.
Link: AsciiDoc Multiple Output Formats -
Article, Book and Manpage are part of AsciiDoc specification.
-
Convert to HTML, PDF, DocBook and more.
-
Supported by GitHub and GitLab; auto-renders AsciiDoc files just like Markdown (eg. README file).
-
O’Reilly has official support to publish AsciiDoc books.
Link: Write books in AsciiDoc -
Easy to separate one big AsciiDoc file to multiple files and import them in main file.
-
Can also import CSV data to fill tables; import program files or any other files to fill code blocks.
-
It has official specification written by AsciiDoc Working Group at Eclipse Foundation.
-
It has official Technology Compatibility Kit (TCK) to test implementations against specification.
One thing to note here is that the main three implemenations of AsciiDoc are in Ruby, Java and JavaScript (Link: AsciiDoc Tools). So, one might need to write an AsciiDoc implementation in Odin for single binary implementation. (I am actually trying to write one, but not sure when I will be able to complete it or how good it will be.)
AsciiDoc can be used for Doc Comments and other documentation for writing very good technical documentation.
So, what are your opinions?