Re: Documentation

[Scott Wimer <scottw dev cgibuilder com>]

Mike,

I don't know how big of a concern this is going to be.  All the API
function documentation (in the current state) looks like it will be
inside of one big comment.  I'm half tempted to propose that we just use
Welder's data file format for that comment block.  :)  That's probably
not an approach that will be comfortable for every body though.  It is
a pretty simple format to work with though (looking something like this):

/**
$F_name=
this_function_name
$Param_1=
paramater 1 name:   paramater 1 description
$Param_2=
paramater 2 name:   paramater 2 description
$Constant_1=
constant 1 name: constant 1 description
$Func_desc=
Text of the function description
blah blah
$Return_desc=
an integer indicating the state of some ....
*/

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.

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

regards,
scottwimer

On Sat, 17 Oct 1998, Michael Chamberlain wrote:

> On Thu, Oct 15, 1998 at 06:12:51PM -0500, Miguel de Icaza wrote:
> > Text inside the descritpion can have any of the following special tags
> > on the beginning:
> > 
> >    @name:   reference to a parameter.
> >    %name:   reference to a constant.
> >    name():   function reference.
> 
> I would suggest that in text that is (reasonably) closely related to code,
> it would be better to use symbols that aren't likely to be used in the code
> itself- '%' has its own meaning in C, but neither '$' nor '@' will normally
> be used. Personally, I think '$' would be a good identifier for parameters,
> as it matches shell variables, and @ could be used for constants.
> 
> Also, is there any method of escaping the above symbols, and/or any way of
> adding other markup. <...> can be used, but again takes away symbols that
> are often used in code, which may not be a good idea. An alternative would
> be something like @{...} or @<...>, or even @@keyword /
> @@keyword{parameters}. This could allow @@{@}, @@{$} for the odd occasion
> when those two symbols need be used, and otherwise leaves everything but
> '@' and '$' as a literal symbol.
> 
> Thoughts?
> 
> Mike.
> -- 
>  _____________________________________________
> | Michael Chamberlain | The best response to  |
> | Honours, Comp.Sci.  | a rhetorical question |
> |   RMIT, Australia   |  is the wrong answer  |
> 
> 
> -- 
>          To unsubscribe: mail gnome-list-request@gnome.org with 
>                        "unsubscribe" as the Subject.
> 
> 

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