1. comments -> documentation
- Posted by David Cuny <dcuny at LANSET.COM> Jul 05, 1998
- 445 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
2. Re: comments -> documentation
- Posted by Ralf Nieuwenhuijsen <nieuwen at XS4ALL.NL> Jul 06, 1998
- 450 views
Brilliant! If you don't want to I'll give it a shot. I'll just study your preproccesors a bit.. Ralf.. David Cuny suggested: >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 >