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
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
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.
Is there a preamble aspect to AsciiDoc, in the sense that macros can be added? Because that would lead to a range of different styles, making the docs less readable in-code, for outsiders at least. Where would those macros even be defined?
One thing to note here is that the main three implemenations of AsciiDoc are in Ruby, Java and JavaScript (Link: AsciiDoc Tools).
I think Typst solves this issue because its compiler can be used as a library. Again, there’s a risk of docs fragmentation because Typst essentially is a scripting language. It’s also more verbose than Markdown or AsciiDoc in a few spots, for example a link is #link("")[]. At the same time, Typst’s codebase now uses Typst itself for the docs. Similar to AsciiDoc, HTML and PDF exports are possible. By the way, I noticed your profile’s gradient is really similar to Typst’s
Markdown is the simplest and most concise, right after plain text. I suppose we could use GitHub-flavoured Markdown, since there’s been additions such as callouts by now.
Of course the marking ‘language’ is important, but an agreed-upon set of tags is as much important, as it allows automatic generation of categorised documentation as well as, in perspective, IDE-driven refactoring.
I think such a level of standardisation (beyond syntax details) is one of the major bonus of systems like JavaDoc or Doxygen.
Currently Odin is hinting at something like this with its common “Inputs:”, “Returns:”, “Example:” lines resembling some kind of headers.
Perhaps with Odin 2027 approaching, it would be worth discussing a more formal tag set?
Well, tags are still inherent to the chosen language. Or at least it’s more favourable to have them as such, in my opinion. Whatever fancier syntax, such as @, is used for them, also introduces risk of collision with whatever different language is used.
I thought something similar to code blocks could be used for Example: and Output:, especially because they’re rarely not code:
```example
```
```output
```
Otherwise, I’m curious as to why Inputs: and Returns: aren’t somehow included by .odin-doc, so that they can be verified. It’s easy to miss a parameter in the handmade list.
It’s apparent to me that the use of Returns: is inconsistent already. So why even have this? Doesn’t a neat sentence explain (a procedure’s) purpose?
As for Inputs:, would line-by-line comments for every input be too wasteful?
Perhaps with Odin 2027 approaching, it would be worth discussing a more formal tag set?
I think only Examples: and Output: really need to be considered as tags (as a pair of code blocks). Are there others you have in mind from your experience? For example, I can see JavaDoc has @author? I assume such metadata could be in a comment at the beginning of an Odin package? Something along the lines of:
AsciiDoc addresses this issue by providing a valid syntax for defining custom macros. Writing custom macros with valid syntax is particularly useful for syntax highlighters and parsers, such as Tree-sitter used by code editors. But, AsciiDoc does not provide a mechanism for defining custom macros directly within an AsciiDoc document.
As a result, AsciiDoc documents maintain a consistent style without being affected by custom macros. At the same time, the Odin doc generator can add one or two Odin-specific macros when necessary.
AsciiDoc also provides syntax for assigning IDs and class names to blocks, similar to HTML. CSS can style these elements using their ID or class attributes, while JavaScript can add functionality such as collapsible Accordion GUI Widget.
But, unlike Markdown, AsciiDoc is not tied to HTML. One of AsciiDoc’s explicit goals is to remain independent of HTML and other output formats.
Git uses AsciiDoc for its documentation including the manpages. As I have mentioned in the above post, manpage is one of the three document types that are explicitly mentioned in the specification. Writing manpages in roff/groff typesetting language is not a pleasant experience.
I believe what I meant by macros are attributes in AsciiDoc. They appear to be distinguished by {} from the surrounding text, which is fine by me. What worries me is that the line just disappears whenever an attribute is invalid.
Many document generators and site generators add custom features with custom syntax to Markdown, and these changes do not adhere to neither CommonMark specification nor GitHub Flavored Markdown specification.
That’s true, but callouts and expandables are all Odin seems to need. The former are already in GitHub-flavoured Markdown, and the latter are really HTML-only.
But, unlike Markdown, AsciiDoc is not tied to HTML. One of AsciiDoc’s explicit goals is to remain independent of HTML and other output formats.
Markdown however doesn’t need to be tied to HTML. Could you elaborate on this?
git uses AsciiDoc for its documentation including the manpages. As I have mentioned in the above post, manpage is one of the three document types that are explicitly mentioned in the specification. Writing manpages in roff/groff typesetting language is not a pleasant experience.
What exactly are manpages, those from the CLI? I don’t see how .odin-doc could relate to them, since git itself is a command?
AsciiDoc’s callouts appear to have a fixed style, so for example CAUTION can’t have a different icon? I thought the purpose of .odin-doc was to allow for more variety in docs.
When we use anything other than Markdown, how to parse the comments of that used language?
// Sample // comment
// /* what happens here?
As for the more special formats, I’m not sure where DocBook 5 can be useful, but I can see EPUB 3 be applicable at least to smaller docs.
So, one might need to write an AsciiDoc implementation in Odin for single binary implementation.
To mention this again, how would this AsciiDoc implementation be kept up-to-date?
In it’s current state, the user documentation is the initial contribution from the Asciidoctor project that describes AsciiDoc as interpreted by Asciidoctor. The user documentation is not itself the AsciiDoc Language Specification. Rather, it serves as the reference material from which the AsciiDoc Language Specification will be developed.
Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.
— Paragraph 1, Sentence 1, #INLINE HTML, Purpose of Markdown Syntax - John Gruber
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.
— Paragraph 3, Sentence 1, #INLINE HTML, Purpose of Markdown Syntax - John Gruber
But AsciiDoc does not need to rely on HTML for many advanced features. This is one of the goals of AsciiDoc.
Manpages and Other Documentation
I was talking about Manpages from CLI. I was just giving an example about how it can be used and where it is used.
What I am trying to say is that AsciiDoc can be used for all kinds of documentation required for a software written in Odin.
Can be used for doc comments in the source code.
Can be used for Manpages for the user.
Can be used for user documentation.
Can be used to create PDF, EPUB, HTML, etc from the same AsciiDoc source.
Can be used to create blogs, sites, etc for the software project.
Docs can be themed in any way.
If Odin officially uses AsciiDoc, then software projects written in Odin also tend to use AsciiDoc for its Documentation (Doc Comments, Web Docs, Book, Manpages, etc).
Many software projects written in Rust uses mdBook for documentation because Rust uses it for its official documentation. But mdBook uses Markdown, and file organization and documentation structure is not flexible because mdBook uses Markdown. If it was using AsciiDoc, then the entire documentation structure can be defined in compliance with AsciiDoc Spec, but at the same time, supports more flexible layouts than mdBook. Including/Importing other AsciiDoc documents or any other type of files are flexible, and is mentioned in the AsciiDoc Spec.
AsciiDoc does not have fixed style. Its main purpose is to separate content from presentation.
The purpose of the language is to focus on encoding explanatory or literary information in a clear and concise way, thus keeping content separate from presentation (with the exception of sensible presentation hints in the form of roles and options).
— Paragraph 2, Sentence 1, AsciiDoc Language introduction and purpose - AsciiDoc Spec
AsciiDoc Comments
AsciiDoc uses // for single line comments, and //// and [comment] tag for multi-line comments. AsciiDoc comments inside Odin comments can be simply ignored. I don’t think its hard to parse and ignore AsciiDoc comments inside Odin comments. Is there any problem that I don’t know about?
Are you talking about keeping the implementation up-to-date with the specification? I think the specification is stable for most part. Otherwise, it won’t be used by major software projects.
Most of the Git project documentation is written in AsciiDoc.
Some of O’Reilly Media’s books and e-books are authored using AsciiDoc mark-up.
Red Hat’s product documentation is written in AsciiDoc.
AsciiDoc is usable within GitHub and GitLab.
AsciiDoc has less problems around its syntax
AsciiDoc has less problems around its syntax. The creator of CommonMark Spec, John MacFarlane, talks about this in detail in Beyond Markdown. To fix the problems of Markdown, he created another light markup syntax called Djot.
AsciiDoc uses // for single line comments, and //// and [comment] tag for multi-line comments. AsciiDoc comments inside Odin comments can be simply ignored. I don’t think its hard to parse and ignore AsciiDoc comments inside Odin comments. Is there any problem that I don’t know about?
This was more of an overall observation, for example Typst uses /**/ block comments.
Are you talking about keeping the implementation up-to-date with the specification? I think the specification is stable for most part.
Yes, and I agree, but there still can be additions or removals which could cause incompatibility errors, no? So would there have to be version metadata alongside author and such, to facilitate this issue?
// AsciiDoc metadata
// :Author: John Doe
// :AsciiDocVersion: version
Git and Red Hat both use AsciiDoc for their docs, but not in code which is what you propose AsciiDoc be used as for Odin? I’m curious as to whether there are actual codebases which use AsciiDoc the way Odin would by your suggestion?
Also, just to clarify, my intent was to emphasise that Odin’s docs don’t appear to require very specialised Markdown features apart from tags, and that in my opinion such docs don’t have as much use in the manpages format as git’s.
One way to deal with this would be to allow only some part of the AsciiDoc Spec for Doc Comments in code, but the AsciiDoc parser will be fully compliant with the Spec.
We can choose the features that are stable (which is already enough for Doc Comments). We can add more stable features without breaking backward compatibility.
In short,
fully spec compliant parser that can be used by the Odin ecosystem,
but restricted spec for Odin Doc Comments in code,
which can be extended in the future in a backward compatible way.
