Re: [naviserver-devel] Doc with doctools

[Stephen D. <sd...@gm...>]

On 7/30/05, Zoran Vasiljevic <zv...@ar...> wrote:
>=20
> Am 30.07.2005 um 03:58 schrieb Stephen Deasey:
>=20
> >
> > [ccall [type int] Ns_ConnLocationAppend [type Ns_Conn] [arg *connPtr]
> > [type Ns_DString] [arg dest]]
> >
> > A C-call always has a name, always returns something (even if it's
> > just void), all args are typed and named, etc., and a lot of that can
> > be inferred from position and so on.  But in the above,  the doc
> > writer must redundantly specify [type Ns_Conn] [arg *connPtr].
> >
> > Couldn't the macro ccall just handle a lot of this transparently?
> > Something like:
> >
> > [ccall int Ns_ConnLocationAppend {
> >     {Ns_Conn *connPtr}
> >     {Ns_DString *dest}
> > } {
> >     Describe me here...
> > }]
> >
>=20
> Of course it could. This is how I did it in the first place.
> But, I'm still not sure and will have to investigate this,
> but it appears to me that other parts of the engine (TOC and Index
> generators) can take advantage of those [type] declarations.
> If this is not true, then there is absolutely no reason why
> not to code like that. I made the [ccall=10] resemble the [call]
> but there is no reason why one could/should not make it like:
>=20
>   ccall int Ns_ConnLocationAppend {{Ns_Conn *connPtr} {Ns_DString
> *dest}}
>=20
> I will put this into and give another round.


Great.  Are the macros expanded recursively?  Can ccal output the type
declarations for the benefit of indexes etc.?  Will we be able to
document the Tcl cmds as easily?

Oh, and can the index be categorized (used to live here:
http://aolserver.com/40drafts/ do you remember?) rather than just fill
the screen, as the Tcl API docs do:
http://www.tcl.tk/man/tcl8.4/TclLib/contents.htm ?

Also, is it possible to do things like mark a function deprecated, and
when, so that is doesn't show up in the normal doc index but an index
of deprecated functions is created, grouped by version number.

How do we specify CONST, and can we document args as in, out or inout?
 How about NONNULL args, varargs and format strings?


I'm just wondering how flexible this thing is.  My mental model is
that it just calls [subst] on the man page source, so things like
literal text would seem hard to hide or move around...