Re: Gnome Developer's documentation.

[Gary V Vaughan <garyv aethos co uk>]

Having proof read this again I noticed that it is very C-centric, but I just
because I worded the way I have doesn't mean it can't be applied to perl or
guile...

On Fri, Feb 06, 1998 at 06:34:35AM -0700, Mark Galassi wrote:
> Hmm: I started writing a long answer thinking that you were asking
> about how to format code and comments in a <programlisting>.  Then I
> actually read your text!

=)O|

>     Gary> I was wondering (Mark?) whether sgml (or XML or somesuch) is
>     Gary> flexible enough that one could write a DTD so that the sgml
>     Gary> parser would scan the annotated C (or whatever) source files
>     Gary> directly and effectively ignore the non-documentation bits
>     Gary> while formatting the documentation directly from tags in
>     Gary> source comments?
> 
> Whereas I think it is possible to choose your delimiters in SGML, I
> don't think you can mix tags delimiters: if you are using < and >,
> then you cannot start using /* and */ as delimiters (which wouldn't
> really be right anyway -- you would want /* to be equivalent to
> <begin-C-comment> or something).

I was thinking of `/*<' and `>*/' as a superset of C comments so that cccp
would strip them out for compilation... but as Mark says:

> If C comments and source happened to (by some lucky chance) behave in
> an SGML-ically correct manner, then I would look into that
> possibility.  Unfortunately C comments do not balance, and neither do
> Lisp and C++ comments, which use a newline as end-of-comment.

Yeah, I guess I knew this intuitively already...

> So pre-processing the source is probably the only way.  That's OK
> because you usually have Makefiles anyway.

True, but someone has to come with a pre-processor!

> [I can't find it in the GNU standards right now] It is discouraged to
> try to write documentation from comments.  This is because very good
> documentation should be written with care for the whole context, and
> not just by extracting pasting pieces of information together.

Hmmm. I hadn't thought of it that way...  I think I need to retract my
comment about it being useful to get *some* (poor) documentation from
sources which weren't written with the documentation in mind. 

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.

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;

  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.
     
  b) The documentation is in the code, so the maintainer is less likely to
     allow them to drift out of synch.
     
  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.

But I'm open to persuasion.  Honest =)O|

Cheers,
		Gary V Vaughan
--
{#include #.signature#}
WARNING:  Cannot find '.signature' template file

PGP signature