This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: embedded docs
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: Randy Dunlap <randy dot dunlap at oracle dot com>
- Cc: systemtap at sources dot redhat dot com
- Date: Thu, 14 Feb 2008 17:20:35 -0500
- Subject: Re: embedded docs
- References: <20080214202138.GE31776@redhat.com> <47B4ADEA.6070901@oracle.com>
Hi -
On Thu, Feb 14, 2008 at 01:08:58PM -0800, Randy Dunlap wrote:
> [...]
> >* embedded javadoc(?) comments, javadoc-generated man pages (possible
> > to be compact enough?), no direct translator support [depends on doc
> > generator tool]
> >[...]
> * embedded kernel-doc notation (use existing tools)
Yes, a special case of "javadoc(?)", and like doxygen, creates pretty
wordy documentation. (I wonder whether has anyone here has used
kerneldoc "in anger" - that is, regularly read stuff generated by the
these docbook tools?)
> * use Asciidoc (like the git content tracker uses) (probably more
> for standalone content than it is for embedded content)
Likewise.
Here's another way to rephrase the issues under contention:
* Do you agree that the status quo needs fixing?
* Do you believe that a relatively verbose man page suite (e.g., one
document per probe point) is likely to be useful?
* Do you agree that there is value in having the translator itself
process these (e.g., for listings mode; for documentation coverage
measurements)?
- FChE