[ruby-talk:24645] Re: kill rdtool?

> > How does it work Dave?  Do you look for a particular set of keywords
> > that are capitalized and followed by a colon?  Or just any word that is
> > capitalized and followed by a colon?
> 
> Any word at the start of a line that ends with a colon starts a new
> section. The various output formatters know how to handle specific
> sections, the rest just take a default section formatting. I'm
> thinking that this is both easy to use, natural to read, and open
> ended: if you want to add new section types you just write output
> handlers for them.

Note that doxygen has three different types of tags. Section tags,
that work as suggested above. Line tags, that extend to the end of the
line and word tags that affect a single word. This suggestion only takes
care of the first type.

Someone suggested using Wiki-style markup for inline style changes. The
drawback I see with that is that it is not extensible. There is no easy
way of adding new tags. You can add more and more formatting rules,
but after five or so they get hard to remember and the parser becomes a
mess.

I think that there should only be a very small number (if any) of 
Wiki rules, perhaps only *this* and _this_. Not strange beasts such as
````this''''. And then there should be another, extensible mechanism
for doing more complicated inline markups. It could either be doxygen
based (with @markups for lines or words) or XML-based.

Another interesting question is how dependent the documentation format
should be of the Ruby parser. I think there are two good options

	a) Use the full ruby parser (borrow the yacc file).

	b) Use a very small set of rules that can be easily
	   understood by the user.

And one bad option

	c) Use a large number of complicated regexps to get something
	   that works 'almost' as the real Ruby parser. When you find
	   that it doesn't work with some code, add a new special case
	   rule to handle that code.

Option (c) apart from being unmaintainable is also unpredictable. If
a user gets garbage from the documentation system he has to read
through dozens of complicated regexps to find out what the problem is.
In that case I think (b) is much better. We acknowledge that we do not
have a full ruby parser and make it very clear to the user which types
of expressions it can handle.

I've written a doxygen-like documentation system for Ruby which I've
used to autogenerate documentation for some of my projects. (You can
find some autogenerated output here:

http://www.acc.umu.se/~r2d2/programming/ruby/webfetcher/webfetcher.html

). In that system I removed the need for complicated parsing by
requiring the user (me) to mark the end of modules and classes with
documentation comments, i.e.:

	## A module that does bla bla bla
	module A

		## A class that does bla bla bla
		class B

			## Does bla bla bla
			def f
				...
			end

		##
		end

	##
	end

That way I didn't have to figure out which end's belonged to
functions, which were parts of strings, etc.

Another somewhat interesting thing I did was that I allowed the line
that was documented to be a comment. This lets the user add comments
for functions that are generated by evals, or in other dynamic ways,
e.g.:

	## Returns the name of the user
	# def name

	## Returns the mail address of the user
	# def mail

	def method_missing(x)
		if [:name, :mail].include?(x)
			@user.data[x]
		else
			super
		end
	end

I think some support support for things like this is needed in a
language that is as dynamic as Ruby.

If you are interested in looking at the code (which is in beta) I can
post it to the list.

// Niklas