You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by co...@hyperreal.org on 1998/05/03 03:24:11 UTC
cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html dict-ap_destroy_pool.html dict-ap_make_sub_pool.html
coar 98/05/02 18:24:11
Added: apidoc README dict-ap_cpystrn.html
dict-ap_destroy_pool.html
dict-ap_make_sub_pool.html
Log:
Some initial population for the API docco development directory.
Seeds as it were..
Revision Changes Path
1.1 apache-devsite/apidoc/README
Index: README
===================================================================
This directory (apidoc) is the development area for an effort to document
the Apache Web server API (Application Programing Interface). In its
current incarnation, there are four types of files here:
. a data file (api.list) that contains a record for each API entity; this
file is internally documented as to format
. a template file (api-dict.html) which is used as the basis for the
assembled documentation
. HTML fragment files (e.g., dict-ap_destroy_pool.html), one per API
entity, that contain the actual documentation for the entities
. a Perl script (mkapi) which puts all of these together to generate a
single monolithic documentation file
There are currently four types of API entities defined: routines, constants,
structures, and global data cells.
The assembled output file labels each entity as a link target; the name
of the target is the entity name (e.g., HREF="#OK", HREF="ap_die").
Entity references in specifications and examples are automatically linked
to the appropriate definitions (e.g., the 'request_rec' text in the example
"ap_child_terminate(rerquest_rec *r)" is automatically a link to the
definition of the request_rec structure).
Documentation fragment files should look like this (leading whitespace
included):
<P>
..entity documentation..
</P>
<P>
..more docco..
</P>
1.1 apache-devsite/apidoc/dict-ap_cpystrn.html
Index: dict-ap_cpystrn.html
===================================================================
<P>
Copies at most <SAMP>numbytes</SAMP> of <SAMP>str</SAMP> to <SAMP>buf</SAMP>.
Differs from <SAMP>strncpy()</SAMP> in that <SAMP>buf</SAMP> is
<EM>always</EM> null terminated, but is <EM>not</EM> null filled.
Therefore, <SAMP>buf</SAMP> should always be at least
<SAMP>numbytes + 1</SAMP> bytes long.
Returns a pointer to the terminating <SAMP>'\0</SAMP>'.
</P>
1.1 apache-devsite/apidoc/dict-ap_destroy_pool.html
Index: dict-ap_destroy_pool.html
===================================================================
<P>
This function will recursively destroy the specified
<A HREF="#pool">pool</A> allocation area and any sub-pools of it,
making any memory allocated to them available for use elsewhere.
</P>
1.1 apache-devsite/apidoc/dict-ap_make_sub_pool.html
Index: dict-ap_make_sub_pool.html
===================================================================
<P>
This function creates a new <A HREF="#pool">pool area</A>
for memory allocation. The
new area is considered to be a "child" of the pool
passed to the routine; this permits a hierarchy of related storage
areas. When a pool is destroyed (see
<A HREF="#ap_destroy_pool"><SAMP>ap_destroy_pool</SAMP></A>),
any sub-pools it may have are also destroyed recursively.
</P>
<P>
An example of when this hierarchy concept is useful can be found in the
<A HREF="http://www.apache.org/docs/mod/mod_autoindex.html"
>automatic directory listing module</A>. Since the module can't
tell in advance how many files it will have to list, nor how long the
names will be, nor what other functions might need to allocate memory
to process the request, it creates a sub-pool of the one associated
with the request, does the <em>per</EM>-filename processing in
it, and clears it for each new file.
</P>
<P>
If the pointer passed to <SAMP>ap_make_sub_pool</SAMP> is <CODE>NULL</CODE>,
a new top-level (<EM>i.e.</EM>, parentless) pool is created. This
is generally not recommended, however, since the only record of a
pool's existence is the pointer returned - a simple logic error can
result in pools being created and lost, along with any allocations
made in them. Most pools are created to deal with <EM>per</EM>-request
processing, and hence should be sub-pools of the request's pool
(<A HREF="#request_rec"><SAMP>r->pool</SAMP></A>) to ensure that
they are properly cleaned up on request completion.
</P>
Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html
dict-ap_destroy_pool.html dict-ap_make_sub_pool.html
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Ben Laurie wrote:
>
> Oh, I see. Why don't the doc files get it done automatically, then?
I didn't do that in the current version for a few reasons:
. The doc file is included verbatim; someone wrote it to look
the way it does.
. Marking up the doc file contents would almost certainly push
lots of lines past column 80.
. Some sections would probably end up so liberally sprinkled
with links as to be annoying.
. Each link adds 16 bytes to the file.
. Dealing with word forms gets difficult - should "pool" be a
link but "pools" not?
. What if a doc file talks about the server's "pool of children"?
Or "the module source files"? Parsing by intent is a little
problematical..
However, most of these would only apply to common multi-value words
like "pool" or "module" and so it might not be a big deal. I'm
not opposed to giving it a try.. but I don't think it would be an
improvement.
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://Web.Golux.Com/coar/ASFD/>
Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html
dict-ap_destroy_pool.html dict-ap_make_sub_pool.html
Posted by Ben Laurie <be...@algroup.co.uk>.
Rodent of Unusual Size wrote:
>
> Ben Laurie wrote:
> >
> > If that's true, why do you have...
> >
> > > 1.1 apache-devsite/apidoc/dict-ap_destroy_pool.html
> > >
> > > Index: dict-ap_destroy_pool.html
> > > ===================================================================
> > > <P>
> > > This function will recursively destroy the specified
> > > <A HREF="#pool">pool</A> allocation area and any sub-pools of it,
> > This..^^^^^^^^^^^^^^^^ ?
>
> I don't think I understand the question.. That's the doc file for the
> routine. Only the example and definition sections are automatically
> parsed for link targets. It's perfectly reasonable to add links to
> the doc file; that's why the README explains the target naming.
>
> What am I missing?
Oh, I see. Why don't the doc files get it done automatically, then?
Cheers,
Ben.
--
Ben Laurie |Phone: +44 (181) 735 0686| Apache Group member
Freelance Consultant |Fax: +44 (181) 735 0689|http://www.apache.org
and Technical Director|Email: ben@algroup.co.uk |
A.L. Digital Ltd, |Apache-SSL author http://www.apache-ssl.org/
London, England. |"Apache: TDG" http://www.ora.com/catalog/apache
Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html
dict-ap_destroy_pool.html dict-ap_make_sub_pool.html
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Ben Laurie wrote:
>
> If that's true, why do you have...
>
> > 1.1 apache-devsite/apidoc/dict-ap_destroy_pool.html
> >
> > Index: dict-ap_destroy_pool.html
> > ===================================================================
> > <P>
> > This function will recursively destroy the specified
> > <A HREF="#pool">pool</A> allocation area and any sub-pools of it,
> This..^^^^^^^^^^^^^^^^ ?
I don't think I understand the question.. That's the doc file for the
routine. Only the example and definition sections are automatically
parsed for link targets. It's perfectly reasonable to add links to
the doc file; that's why the README explains the target naming.
What am I missing?
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://Web.Golux.Com/coar/ASFD/>
Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html dict-ap_destroy_pool.html dict-ap_make_sub_pool.html
Posted by Ben Laurie <be...@algroup.co.uk>.
coar@hyperreal.org wrote:
> The assembled output file labels each entity as a link target; the name
> of the target is the entity name (e.g., HREF="#OK", HREF="ap_die").
> Entity references in specifications and examples are automatically linked
> to the appropriate definitions (e.g., the 'request_rec' text in the example
> "ap_child_terminate(rerquest_rec *r)" is automatically a link to the
> definition of the request_rec structure).
If that's true, why do you have...
> 1.1 apache-devsite/apidoc/dict-ap_destroy_pool.html
>
> Index: dict-ap_destroy_pool.html
> ===================================================================
> <P>
> This function will recursively destroy the specified
> <A HREF="#pool">pool</A> allocation area and any sub-pools of it,
This..^^^^^^^^^^^^^^^^ ?
Cheers,
Ben.
--
Ben Laurie |Phone: +44 (181) 735 0686| Apache Group member
Freelance Consultant |Fax: +44 (181) 735 0689|http://www.apache.org
and Technical Director|Email: ben@algroup.co.uk |
A.L. Digital Ltd, |Apache-SSL author http://www.apache-ssl.org/
London, England. |"Apache: TDG" http://www.ora.com/catalog/apache