OpenEuphoria

comments -> documentation

• Posted by David Cuny <dcuny at LANSET.COM> Jul 05, 1998
• 599 views

Like most programmers, I don't really like to write documentation. But I
understand that it is a "necessary evil" of programming. So it caught my
attention when I was browsing through some C code stuff something like the
following:

/*!
    \class FooWidget foo.h
    \brief The FooWidget is used for building spockets.
    \ingroup bar

    The FooWidget does a lot of interesting things. Blah blah blah.

    <img= src=foowidget.gif>
*/

Each function definition was preceeded by a comment, along the lines of:

/*    \fn bool QFooWIdget::isOn() const

    Returns true if FooWidget is on.

*/

Not suprisingly, the documentation that came along with the code was nicely
formatted HTML, containing the information supplied in the comments. And
there were a series of header pages as well, also generated from the
\class... macros.

Obviously, it occured to me that something like this *might* be a good thing
to have in Euphoria, for lazy programmers. It would certainly make it a lot
easier to keep the code and comments in sync, and the output would be
standardized. Heck, you could potentially also generate something like EE's
.HLP files, and have on-line help for libraries a standard feature.

I'm *not* volunteering for the project - I'm just wondering what other
people think of the idea.

-- David Cuny