Re: Literate programming

[Simon Britnell <ughbash yahoo com>]

I can testify to the usefulness of extracting documentation from code.

I've worked on two projects that this worked well on.  in one,  we had
a program which extracted comments and tags from C source and in
another I've used javadoc.  It works brilliantly.

The C comment extractor worked like this:

PUBLIC
/*******
 * Comment on what this is / does
 *******/
int my_func(		/* Comment about return value*/
	char *p1,	/* Comment about 1st parame */
	int p2		/* Comment about 2nd param */
)
{
	/* do stuff */
}

This was extracted into the .h file as follows:

/*******
 * Comment on what this is / does
 *******/
int my_func(		/* Comment about return value*/
	char *p1,	/* Comment about 1st parame */
	int p2		/* Comment about 2nd param */
)
;

It doesn't make great user docs, but it's great for system and design
docs.  Want to know how to use things?  Look in the .h file.  This
also has the advantage that the .h needs to be shipped with the
compiled lib to be able to link anyway.

---Stefan Nobis <snobis@usa.net> wrote:
>
> Mark Galassi <rosalia@cygnus.com> writes:
> 
> >     >> Are we really wedded to the idea of extracting documentation
> >     >> from the
> > 
> > I think we are not wedded to it.  Horacio did a flurry of work to
get
> 
> But why not? I think the idea is very superior and projects like TeX
> from Donald E. Knuth shows that literate programming is not a bad
> idea. But if we really want a literate programming paradigm to work
we 
> should not use such tools like docbook which at best goes half the
way 
> to literate programming but tools like noweb - a true literate
> programming system. And then there will no problem with
> documentation.
> 
> -- 
> Until the next mail...,
> Stefan.
> 
> 
> -- 
>          To unsubscribe: mail gnome-list-request@gnome.org with 
>                        "unsubscribe" as the Subject.
> 
> 

_________________________________________________________
DO YOU YAHOO!?
Get your free @yahoo.com address at http://mail.yahoo.com