Dave Thomas
3/29/2008 10:21:00 PM
On Mar 29, 2008, at 4:20 PM, Rodrigo Almeida wrote:
> Currently RDoc already can be extended to add support for other forms
> of markup (see doc for RDoc::Page), but this could be improved, as to
> accept additional markup tags and modifiers in an easy way. Let's say
> I used to work with java and wanted to comment a method like in the
> example below.
>
> # Method description here
> #
> # ::params::
> # url: an absolute URL giving the base location of the image
> # name: the location of the image, relative to the url argument
> # ::return::
> # the image at specified URL
> # ::see::
> # Image
> #
> def load_image(url, name) #:takes: String, String; #:returns: Image
>
> It should be viable for someone to come up with an RDoc extension that
> can generate the JavaDoc-like output from the comments above without
> excessive digging into RDoc's source.
All neat and worthy ideas.
I'm the last person to defend RDoc--it has already served it's
purpose, and is long due for replacement.
However, one of the goals of RDoc was to not pollute the source code
with markup. I want the comments to look like comments, and not like
something put there for the convenience of a documentation tool.
That's why, for example, RDoc does automatic hyperlinking when it can--
it seems better to live with the fact it sometimes gets it wrong
rather than live with extra stuff in the code. It's also why RDoc will
produce halfway useful documentation for a source file containing no
comments at all.
Anyway, I'd suggest that your example here could equally well be written
# Takes the base location of the image and the name of the image (both
as strings)
# and returns the absolute image url. Also see the Image class.
def image_url(base, image_name)
...
end
Remember that, unlike JavaDoc, RDoc already extracts the names of
parameters from the source code. Give them meaningful names, and I'm
not sure you need to have tables that duplicate those names in the
comment block.
Dave