Re: Gnome Developer's documentation.]

[Cheng-Chang Wu <ccwu ccwu ping de>]

I have forget to CC: it to gnome-list

-- 
Cheng-Chang Wu

---

• From: Cheng-Chang Wu <ccwu ccwu ping de>
• To: gvaughan oranda demon co uk
• Subject: Re: Gnome Developer's documentation.
• Date: Fri, 06 Feb 1998 20:50:48 +0100

Gary V Vaughan wrote:
> But, does this make Knuth(?)'s cweb/fweb a `Bad Thing'?
> 
> To be fair, that is a rhetorical question.  Cweb is undoubtably a useful
> piece of software, but it does require a shift of mindset -- you need to
> think of writing your code *as* writing your documentation, or better yet
> you need to think of what code you need to write *while* writing your
> documentation.

Take a look at c2man. It seems don't require a shift of mindset and can
be used for my old sources without rewriten:)

The following ist cited from a document of c2man:

    I have implemented one such documentation compiler
    for the C language called "c2man", which is freely
    available[3]. The response from users has been
    extremely encouraging; I suspect this is partly
    because of the wide variety of styles of comment
    placement that are recognised: it often correctly
    recognises comments that weren't written with c2man
    in mind at all. While it's use is focused solely on
    functional interface documentation and it doesn't have
    anywhere near the power of a full Literate Programming
    system, the focus is on reducing the effort required
    by the programmer to the absolute minimum, and seeing 
    how much documentation we can get essentially "for free".
 
> 
> Having given this some more thought, I think that it might be better to
> write public (as in "useful to other (sub-)projects") header files in some
> as yet undetermined style which allows a preprocessor to extract developers'
> interface documentation from these headers to be used as *part* of the
> (sub-)project documentation as a whole.  This serves at least 4 purposes;

Agreed, and that why I think the proposal to add a docbook backend to
c2man is a good idea.
 
>   a) The only bit of your code other (co)developers should care about
>      (assuming they trust you to come up with a halfway decent implementation)
>      is the interface.  So the only part that needs formal (ie more than
>      comments in the source) documentation is the interface, which should be
>      exported by one or more headers.
Agreed.
 
>   b) The documentation is in the code, so the maintainer is less likely to
>      allow them to drift out of synch.

Agreed.
 
>   c) Some of the tedium of describing structures and call sequences can be
>      factored into the preprocessor, and save the writer some trouble.
> 

>   d) Reading the headers really will give the reader the details necessary to
>      use a package effectively.  I am sometimes annoyed by the lack of
>      comments in headers when paired with inadequate man-pages,  this may be a
>      way to save this happening all over again.
> 
> Taking into account the mindset-shift needed to embed `good' documentation in
> sources, and assuming the writer takes/has the time to write some `wrapper'
> documentation to pull it all together, I still think this is a worthwhile
> idea.

Agreed.

I've just got c2man and find that perhaps c2man is just the preprocessor
you have described?
 
> But I'm open to persuasion.  Honest =)O|
> 
> Cheers,
>                 Gary V Vaughan
> --
> {#include #.signature#}
> WARNING:  Cannot find '.signature' template file
> 
>     ---------------------------------------------------------------
> 
>                Part 1.2   Type: application/pgp-signature

-- 
Cheng-Chang Wu

---