Menu
In Python, when commenting a function, you can do it in a way that makes it easier for documentation to be automatically generated. They refer to it as a docstring.
Now that I've made an abstract class in Groovy that I'd like to pass around, is there a standard way I should comment it as well? Are there any Groovy tools to generate basic documentation from code comments?
600
A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Also, it is a common practice to generate online (html) documentation automatically from docstrings.
All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings. A package may be documented in the module docstring of the __init__.py file in the package directory.
Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function. An object's docstring is defined by including a string constant as the first statement in the object's definition.
Docstrings can be further broken up into three major categories: Class Docstrings: Class and class methods. Package and Module Docstrings: Package, modules, and functions. Script Docstrings: Script and functions.
Documenting Groovy with Groovydoc is a nice starting point:
"Groovydoc was introduced in 2007 to provide for Groovy what Javadoc provides for Java. Groovydoc is used to generate the API documentation for the Groovy and Java classes that compose the Groovy language."
112
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
