I greatly appreciate that [a doc gen tool is included with
Nim](https://nim-lang.org/docs/docgen.html), 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
Run
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}."
Run
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.
