I greatly appreciate that a doc gen tool is included with Nim, but I noticed that it's quite minimal compared to older, well-established documentation generators like Doxygen and Sphinx.
Those doc gen tools support all kinds of special syntax and directives allowing the user to describe parameters and return values in their own sections, embed examples that will be rendered with code formatting, cross-link to other entities in the current code base, etc. Sphinx for example supports full reStructuredText syntax and provides a large amount of built-in directives for Python programs, and can also parse a handful of other popular documentation formatting conventions.
I wouldn't expect all this functionality to be present in the Nim doc gen tool, but one side benefit of all this functionality is that they impose somewhat-standardized formatting and syntax on the in-source documentation. Has such a standardized formatting and syntax been proposed for Nim? And is there any interest from the community in supporting more "structured" functionality in the Nim doc generator?
To provide a more concrete example, here's a hypothetical (and somewhat contrived) Python function, with a "Google-style" docstring and type annotations, that can be parsed by Sphinx:
def make_greeting(username: str, returning: bool = False) -> str:
""" Generate the user greeting
Args:
username: The user's username; assumed to already be clean and validated.
returning: If true, use a message appropriate for a returning user. Otherwise, use a message appropriate for a first-time user.
Returns:
The greeting message.
Example:
.. code-block:: python
msg = make_greeting(user.username, returning=user.is_returning())
"""
if returning:
greeting = f"Welcome back, {username}."
else:
greeting = f"Nice to meet you, {username}."
return greeting
Hopefully it's obvious that, regardless of whether this is intended to be parsed by a doc gen tool or by humans reading the source code, it's fairly clean and readable, and also follows an unoffensive standard format.
Now for Nim, all that appears to be supported by the current doc gen tool is this:
include strformat
proc makeGreeting(username: string, returning: bool = true): string =
## Generate the user greeting
if returning:
result = &"Welcome back, {username}."
else:
result = &"Nice to meet you, {username}."
Obviously I could just re-use the same conventions that I use in Python, but I also want to use conventions that are familiar to other Nim programmers when I am writing Nim code rather than just making things up as I go.
Nim is documented with itself, and documentation is nice.
You do not need to annotate the types of the arguments because it has static typing, and you can see the types and argument names on the documentation and code, the returns are documented the same way as the arguments, typeless arguments and returns are not supported, for the examples it has runnableExamples that keeps the documentation in sync with the code.
But feel free to contribute improvements on the documentation and docgen.
I believe it is a dialect of reStructuredText not markdown.
It's grown to support many markdown features too.