Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.arch.embedded > #31124
| From | Stephen Pelc <stephen@vfxforth.com> |
|---|---|
| Newsgroups | comp.arch.embedded |
| Subject | Re: Ftn I/Os documentation best practices |
| Date | 2022-06-28 08:30 +0000 |
| Organization | A noiseless patient Spider |
| Message-ID | <t9ee7a$11moq$1@dont-email.me> (permalink) |
| References | <t9acer$d1t$1@dont-email.me> <t9bmlm$bic9$1@dont-email.me> <t9chnf$kve$1@reader2.panix.com> |
On 27 Jun 2022 at 17:18:07 CEST, "Grant Edwards" <invalid@invalid.invalid>
wrote:
>> If you are just putting these things in comments, then they will get out
>> of sync with the code.
>
> I'd have to agree. I've worked with many projects and third-party
> libraries over the decades which had a big template of comments for
> every function which described the input/ouput parameters, return
> value, global variables used, and so on.
>
> Often these templates generated documents by using something like
> Doxygen.
For the last 20 years or so, virtually all our manuals have been created
by our own "literate programming" system called DocGen. DocGen is
optimised for Forth, but it would not be a big job to write a version for C.
DocGen diverges from Doxygen and friends in a several ways. In
particular it does not need template blocks. If your C code is so bad
that another programmer cannot read the declaration, you need far
more help than DocGen or Doxgen can give you. The main entry
for a function follows the declaration
float someFunc( int how, double x, double y )
// *G The purpose of *\c{someFunc} is ...
// ** ...
{
...
}
The lines starting // *x are formal comments to be processed by
DocGen. The *X parts are formatting commands, and the *\<name>{}
parts are text macros.
The ideas behind DocGen are that the code and the documentation
are never separated, and that the DocGen portion is not much larger
than the descriptive comments you should have in your code anyway.
Keeping the code in sync with the documentation is a matter of
company culture and management.
Whenever we receive third party code to include in our products,
we *always* DocGen it before release and we *always* find some
bugs. Overall, I estimate that writing the documentation alongside
the code costs about 10% extra, paid for by the reduction in bug level.
Stephen
--
Stephen Pelc, stephen@vfxforth.com
MicroProcessor Engineering, Ltd. - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, +44 (0)78 0390 3612, +34 649 662 974
http://www.mpeforth.com - free VFX Forth downloads
Back to comp.arch.embedded | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-26 12:35 -0700
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-27 09:36 +0200
Re: Ftn I/Os documentation best practices Grant Edwards <invalid@invalid.invalid> - 2022-06-27 15:18 +0000
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-27 19:52 +0200
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-27 14:34 -0700
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-28 13:48 +0200
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-28 08:30 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-28 05:49 -0700
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-28 14:35 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-28 11:33 -0700
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-29 12:36 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-29 06:39 -0700
csiph-web