You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by rb...@covalent.net on 2000/07/23 20:29:04 UTC
Making the new APR docs.
Converting APR's docs to use ScanDoc is now complete. :-) To build the
current docs:
cd src/lib/apr
make docs
This will generate a bunch of .html files in src/lib/apr/docs.
A couple of issues that we still have:
The format isn't perfect. I am working with the authors of ScanDoc to fix
some of the problems.
The images. All of the current images used in APR's docs are ScanDocs
default images. These need to be changed. Which brings up another
issue. Does APR use the feather, or should we create another image for
APR?
The docs could probably use some touching up, but we should all be working
on that. :-)
Please, review this stuff, because I am planning to do the same basic
thing to ALL of Apache in the next few weeks/months. I want to finally
document the Apache API, and using ScanDoc to do it makes sense to me.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Making the new APR docs.
Posted by rb...@covalent.net.
<snipped>
> I'll go ahead and make these changes if folks agree with them.
Feel free. I did a quick conversion so more people could help. I REALLY
didn't think about the formating, because most of this was done with
regex's.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Making the new APR docs.
Posted by "Life is hard, and then you die" <ro...@innovation.ch>.
On Sun, Jul 23, 2000 at 11:29:04AM -0700, rbb@covalent.net wrote:
>
> Converting APR's docs to use ScanDoc is now complete. :-) To build the
> current docs:
>
> cd src/lib/apr
> make docs
>
> This will generate a bunch of .html files in src/lib/apr/docs.
Cool! This is *much* better - nice work.
> A couple of issues that we still have:
[snip]
> The docs could probably use some touching up, but we should all be working
> on that. :-)
I have a few suggestions.
1) Minor: put an empty line between the description and list of params:
/**
* Shutdown either reading, writing, or both sides of a tcp socket.
*
* @param thesocket The socket to close
* @param how How to shutdown the socket. One of:
...
2) Use html markup instead of <pre>:
/**
* Shutdown either reading, writing, or both sides of a tcp socket.
*
* @param thesocket The socket to close
* @param how How to shutdown the socket. One of:
* <dl>
* <dt>APR_SHUTDOWN_READ <dd>no longer allow read requests
* <dt>APR_SHUTDOWN_WRITE <dd>no longer allow write requests
* <dt>APR_SHUTDOWN_READWRITE <dd>no longer allow read or write requests
* </dl>
* @tip This does not actually close the socket descriptor, it just
* controls which calls are still valid on the socket.
*/
ap_status_t ap_shutdown(ap_socket_t *thesocket, ap_shutdown_how_e how);
(as opposed to:
* @param how How to shutdown the socket. One of:
* <PRE>
* APR_SHUTDOWN_READ -- no longer allow read requests
* APR_SHUTDOWN_WRITE -- no longer allow write requests
* APR_SHUTDOWN_READWRITE -- no longer allow read or write requests
* </PRE>
).
3) I think too much is currently in @tips. Example:
/**
* Read data from the specified file.
* @param thefile The file descriptor to read from.
* @param buf The buffer to store the data to.
* @param nbytes The number of bytes to read.
* @param bytes_read If non-NULL, this will contain the number of bytes read.
* @tip ap_read will read up to the specified number of bytes, but never
* more. If there isn't enough data to fill that number of bytes,
* then the process/thread will block until it is available or EOF
* is reached. If a char was put back into the stream via ungetc,
* it will be the first character returned.
*
* It is possible for both bytes to be read and an APR_EOF or other
* error to be returned.
*
* APR_EINTR is never returned.
*/
ap_status_t ap_full_read(ap_file_t *thefile, void *buf, ap_size_t nbytes,
ap_size_t *bytes_read);
All the tip stuff is really part of the specification here, so it should
go into the description:
/**
* Read data from the specified file. This will read up to the
* specified number of bytes, but never more. If there isn't enough
* data to fill that number of bytes, then the process/thread will
* block until it is available or EOF is reached. If a char was put
* back into the stream via ungetc, it will be the first character
* returned.
*
* <P>It is possible for both bytes to be read and an APR_EOF or
* other error to be returned.
*
* <P>APR_EINTR is never returned.
*
* @param thefile The file descriptor to read from.
* @param buf The buffer to store the data to.
* @param nbytes The number of bytes to read.
* @param bytes_read If non-NULL, this will contain the number of bytes read.
*/
ap_status_t ap_full_read(ap_file_t *thefile, void *buf, ap_size_t nbytes,
ap_size_t *bytes_read);
4) use @return:
/**
* Is there an error on the stream?
* @param fptr The apr file we are testing.
* @tip Returns -1 if the error indicator is set, APR_SUCCESS otherwise.
*/
ap_status_t ap_ferror(ap_file_t *fptr);
should instead be:
/**
* Is there an error on the stream?
*
* @param fptr The apr file we are testing.
* @return -1 if the error indicator is set, APR_SUCCESS otherwise.
*/
ap_status_t ap_ferror(ap_file_t *fptr);
I'll go ahead and make these changes if folks agree with them.
Cheers,
Ronald