I have some spare time and a strong interest in documentation. I’d like to enhance rdoc in a few ways, as I think
it is a wonderful tool. Here is the first of my proposals:
I think that rdoc has one serious shortcoming relative to the other documentation generation tools that I have used
(javadoc and rdoc): rdoc does not have any descriptive markup for source code. That is, it has no way to describe parameters
(@param in doxygen/javadoc), return values (@return in doxygen/javadoc), or possible exceptions (@throw in doxygen,
@throws in javadoc). If one wants functionality like this, one must use the existing markup for formatting purposes.
For instance, for this method definition:
def load(reader, containing_object_name = "")
I have an emacs macro that adds the following above the definition:
#
# ====Description:
#
#
# ====Parameters:
# [reader]
# ?
# [containing_object_name = ""]
# ?
#
# ====Returns:
#
#
I can fill this in, and, given the template that I use, the results look pretty good (see
http://configtoolkit.rubyforge.org/classes/ConfigToolkit/BaseConfig.html#M000017).
This is, however, a poor solution for several reasons:
1.) The formatting of parameters and return values is baked into the source code. Since I can’t really describe parameters
or return values, I’m describing their formatting. Changing the formatting requires changing the source code.
2.) Whether or not the parameters and return values appear reasonably in the output is accidentally dependent on the
template used. If rdoc’s markup could describe parameters and return values directly, however, the template creators
specifically could support these constructs.
3.) This practice is not at all standard in the Ruby community.
I lean towards using the javadoc/doxygen markup as they’re quite standard:
\param
\return
\throw
|
