httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rasmus Lerdorf <ras...@raleigh.ibm.com>
Subject Re: Apache 2000, err Apache 2.0 gets real
Date Mon, 02 Aug 1999 13:52:29 GMT
> Good idea, I'll change the /* *** to /* {{{ later today, and add the 
> /* }}} */ as well.  Just to make sure I've got what you want right, it
> will look like:
> 
> /* {{{ APR ap_open(...)
>  * docs for args and notes
>  */
>  ap_open(...)
>  {  Code for ap_open;
>  }
> /* }}} */
> 
> Is that right?

Yes, that's correct.  But, don't do this just for me.  If nobody else
likes folding editors as much as I do, there is no point.

> I'll leave the ability to add the <HTML> tags in, but I won't get to it
> today.

When I said tagging, I didn't necessarily mean HTML tags.  If we want to
structure things right it should be SGML tags, but this might be taking
things too far.

In PHP I did this:

/* {{{ proto string apache_note(string note_name [, string note_value])
   Get and set Apache request notes */

The 'proto' keyword identifies the entry as a function prototype.  I found
that I wanted to fold other parts of the code using /* {{{ */ ....  /* }}}
*/ and by adding this 'proto' keyword my auto-generation scripts had
something constant to look for when it went through and pulled out all the
user-level function prototypes.  In fact, the script that runs through the
PHP code and pulls out all these is going to be a published author soon.
It is writing an entire O'Reilly pocket reference guide all on its own! ;)

I think the 'APR' tag is fine for that here.  Other parts of Apache should
use their own section identifier which would allow the generation scripts
to generate section-by-section docs based on a given sequence of section
identifiers.

-Rasmus


Mime
View raw message