Re: Documentation

[Michael Chamberlain <mgc cs rmit edu au>]

On Fri, Oct 16, 1998 at 03:51:52PM -0700, Scott Wimer wrote:
> As far as I'm concerned, that'd be easier for me to parse out, but it is
> more important that we have a format that the code authors are happy with.

That was the basis of my suggestion- although I've not actually done any
GNOME stuff (hopefully "yet"), when I've done similar things I've
always found it a pain to have to be careful of "special" characters that
have their own meaning. Sticking source into LaTeX or HTML requires (IMHO)
a not insignificant amount of effort (excluding \verbatim{}, <PRE>) to make
sure that nothing gets mangled.

Given that people writing code do not always enjoy writing documentation,
anything that makes it harder than it could be is something to avoid.

> Since they've already started using the version Miguel described, we'll
> probably end up with something that looks a whole lot like that.

That was why I asked about escaping characters- what if I want to describe
the calculation some function uses:

    x = blahblah % blah
(where blah is a constant, blahblah a parameter)

I now have in the docu-comment:

 * x = @blahblah % %blah

I don't think this is as easy to read as it could be, and would be even
worse if I didn't have the spaces. Also, will whatever tool extracts the
comments handle the '%' by itself? Should I use %% instead?

I think a good challenge is to write a docu-comment that fully explains the
docu-comment format- that way all the quoting issues should be resolved.
>From the specification I saw, it isn't possible to do so because there is
not enough information.

It may not be a problem now, but it could be in the future, and I think it
is best to resolve such things before they become problems.

Mike.
-- 
 _____________________________________________
| Michael Chamberlain | The best response to  |
| Honours, Comp.Sci.  | a rhetorical question |
|   RMIT, Australia   |  is the wrong answer  |