Hi all,
In a previous forum post, I asked whether it's possible to extract the text content of double-hash documentation comments in non-compiler code. When the answer seemed to be "No", I thought I'd polish up my own code for this and put it on Github in case it would be of use to anyone else.
I'd like to announce docstrings.nim, Python-like docstrings that can be extracted at compile time: https://github.com/jboy/nim-docstrings
This module implements Python-style docstrings that can be embedded in the source code of a proc, along with some simple procs and macros that enable those docstrings to be extracted by pragmas at compile-time.
This module is a small, self-contained part of a larger project I've been working on over the last 3 weeks, which I hope to make available soon. These docstrings are used for automatic extraction of introspection documentation from documented procs in my code.
The most important procs and macros provided are:
This example usage code is also provided in the accompanying Nim source file testDocstrings.nim:
import docstrings
proc myProc(x: int, y: string, z: float64): int {. extractdocstrings .} =
## This double-hashed comment is a Nim documentation comment:
## http://nim-lang.org/docgen.html#documentation-comments
##
## It's recognised by Nim's "docgen" utility, which is how the official
## Nim docs are generated. However, I can't work out how to extract the
## text content of the documentation comment from my own code.
##
## Hence, I present extractable Python-style docstrings:
docstring"""This is a Python-style docstring!
It doesn't do anything by itself, but it can be extracted by pragmas like
the ``extractdocstrings`` pragma, enabling non-compiler/non-docgen code
to extract and process the text content of the docstring at compile-time.
"""
echo($x, y, $z) # just something to document...
docstring"""This is another Python-style docstring in the same proc.
There can be any number of docstrings amongst the top-level statements
of a proc. But why would you want multiple docstrings in your proc?
Maybe you don't want a big slab of documentation right between your
function prototype and your function body, pushing the body way down
from the parameters in the prototype. Maybe you want to document your
algorithm step-by-step, integrated with the code.
"""
docstring"""The ``extractdocstrings`` pragma (or better yet, your own
custom pragma that invokes the ``extractAnyDocstrings`` proc, which is
defined in the ``docstrings`` module) will extract all docstrings.
"""
return int(x.float64 + z)
discard myProc(1, "2", 3.0)
When you compile testDocstrings.nim, the docstrings will be extracted and printed to the console at compile-time (in the midst of the compiler output). The output will look like this:
Extracted docstrings: | This is a Python-style docstring! | | It doesn't do anything by itself, but it can be extracted by pragmas like | the ``extractdocstrings`` pragma, enabling non-compiler/non-docgen code | to extract and process the text content of the docstring at compile-time. | | This is another Python-style docstring in the same proc. | There can be any number of docstrings amongst the top-level statements | of a proc. But why would you want multiple docstrings in your proc? | | Maybe you don't want a big slab of documentation right between your | function prototype and your function body, pushing the body way down | from the parameters in the prototype. Maybe you want to document your | algorithm step-by-step, integrated with the code. | | The ``extractdocstrings`` pragma (or better yet, your own | custom pragma that invokes the ``extractAnyDocstrings`` proc, which is | defined in the ``docstrings`` module) will extract all docstrings. CC: testDocstrings
Any comments or suggestions (including any comments or suggestions about my beginner Nim coding style) are welcome!
Enjoy!