Tcl Library Source Code

View Ticket
Bounty program for improvements to Tcl and certain Tcl packages.
Ticket UUID: 1798420
Title: Documenting C functions
Type: Bug Version: None
Submitter: sdeasey Created on: 2007-09-19 21:29:15
Subsystem: doctools Assigned To: andreas_kupries
Priority: 5 Medium Severity:
Status: Open Last Modified: 2007-09-23 08:41:57
Resolution: None Closed By:
    Closed on:
Here's an example:

- In the Synopsis and Functions sections there are no parentheses around the function arguments. They don't look like C functions.

- The argument names are listed, but not their types. It's not clear from the doctools docs how to identify pointers, arrays etc.

- How do do you make doctools arrange it so that when the man pages are installed and a user types

    $ man Ns_SlsAlloc

the Ns_Sls man page appears, which documents all the sls functions?
User Comments: sdeasey added on 2007-09-23 08:41:57:
Logged In: YES 
Originator: YES

With your feedback, I took another go at it and it's looking a lot better:

That's completely not the mental model I had of how the macros worked.

  [call [fun Ns_SlsAlloc]([type Ns_Sls] *[arg sls], [type Ns_Callback] *[arg cleanup])]

After marking up Tcl commands, I imagined each arg to 'call' was a significant element: func name, arg, option, type, etc. But it's actually just a blob of text..(?).

The documentation for doctools doesn't really help. There are no examples. It doesn't tell you when or why you might use a particular macro. It doesn't tell you which macros go together.

How do I handle return values? Do I just add type and arg in front of fun?

(I haven't got as far as structures and other types yet. I'll have to think about it...)

sdeasey added on 2007-09-23 08:31:40:
Logged In: YES 
Originator: YES

Regarding command/function aliases, this seems part of what building a set of man pages is about. Ideally I would point doctools at a directory full of *.man sources and it would output the nroff (as it does now). But also, it would recognise that actually documents half a dozen related functions and would create sym-links: -> etc. This allows a user to type 'man Ns_SlsAlloc' and have the right man page appear.

I think you need the database of which commands are documented on which pages anyway, for the cross referencing to work.

andreas_kupries added on 2007-09-20 23:50:36:
Logged In: YES 
Originator: NO

Side note regarding Ns_Sls.html ... "Ns_Sls} - Socket local storage" shows me that there is a closing brace to many somewhere in the documentation sources.

Regarding parentheses and argument types: When doctools was written it was with the intent of documenting Tcl commands. C functions were not on my mind and so are not really supported. You can document them, but a number of things have to be done manually, like adding parentheses around the whole set of arguments to a function, and adding type names to arguments. We currently do not have any markup commands to highlight types.

Would you be willing to write up a concrete proposal of the extensions (= markup command) needed for clean support on C functions ?

Regarding "How do do you ... arrange", that is completely out of the scope of doctools. It is intended for the conversion of the manpages to HTML, nroff, and the like, however it has no truck with installing the results. That is left to the Makefile (or equivalent buildsystem) of the package being documented.