Re: Documentation

[Scott Wimer <scottw dev cgibuilder com>]

Mike,

As to avoiding munging code that gets embedded in the docu-comments, I'm
not to worried yet.  I'll probably put out a proposed format for the
docu-comments sometime this weekend.  It will basically be the existing
format that Miguel sent out, with some additional information about 
the actual format of the individual pieces.

My entire goal on this is to make the documentation easy for the
programmer to write.  As long as I can still make perl parse it out, 
that will be the driving issue.  Most likely, this won't be a major
problem, since the documentation that has been made to date (in the
source files) is generally well structured.  If and when we need to
loosen the structural requirements, they'll have to be addressed then.

Enough gum flappage, back to work for both of us.  :)

regards,
scottwimer

On Sat, 17 Oct 1998, Michael Chamberlain wrote:

> 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  |
> 

--
Scott Wimer
play  --->    scottw@cgibuilder.com         http://www.cgibuilder.com/
work  --->    scottw@corp.earthlink.net     http://www.earthlink.net/