Re: Documentation

[Michael Chamberlain <mgc cs rmit edu au>]

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  |