Re: Documentation

[Christian Reiniger <warewolf@mayn.de>]

Bjarke Hammersholt Roune wrote:

>First off, with this documentation stuff, how is it supposed to be laid out?
>In other words, how is one supposed to document one's code?

According to the rules defined by the perceps tool.
(Actually this has to be examined - perceps showed very little
progress/activity during the past months. But on the other hand the
homepage is talking about a new maintainer, so things just might speed up
again...)

Basically the comments look like this (some PFile comments already have
that format, especially in the newer files like ppf_PakWThing.h):

//: short, one-line description
//: may be continued on next line
//
// more verbose description (optional)
// over several lines if you want

>I know the documentation is supposed to be before each function. How about
>classes? Documentation that is just generally on a class, rather than any of
>its methods, do you write that before the class? Can you document

Yup.

>data-members (ie, not methods, but something like int m_count) ? Do you need

AFAIK yes.

>to do something special to get this documentation compiler to get that this
>comment is really documentation and not just a comment?

Use "//" comments
Use "//:" at the first comment line

>Should documentation for ppSomeClass::DoSomething be written in the class
>definition, or right before the method implementation?

In the definition I'd say. That's generally the place to look for the
method declarations, so having the comments in the same place makes things
easier.

>How do we comment? Do we set up precondition/postcondition rules? Do we

Only unusual ones. Simple ones like "string parameter must not
be 0" should be clear. Preconditions in internal code are checked via
assertion (ppAssert () macro) and via 
if (!Condition) 
{ 
  ppWarning ("Invalid Arguments");
  return SomeErrorCode; // or an exception, depending on the function
}
in API functions.

>mention all exceptions that could be thrown by a function? Do we mention if

Not neccessarily. The exception specification in the function declaration
is sufficient most of the time. Just sometimes it is good to explain the
reasons for throwing the exceptions.

>a function does memory (de)allocation or if it could potentially cause a
>reallocation of something?

No. We mention if the function returns something that has to be freed by
the caller and the function should (usually) simply fail cleanly if some
allocation in it fails.

>What about protected and private stuff? Do we document that? If not, then

Usually not.

>how do we tell the documentation compiler that a comment about a private is
>not documentation, but just a comment? Also, what if a protected method is

Use /* */ comments. They are ignored.

>supposed to be used by client-code derivations of a class? Isn't it a bit of
>a hostile environment against peole who might want to help out not to tell
>people about what happends in atleast protected methods? (private methods,

Protected methods are a kind of interface for derived classes, so they
should be documented. Private ones are clearly implementation details, so
they should not have interpreted comments (non-interpreted ones are good
however, of course).

>If we do document protected and/or private stuff, then what about stuff of
>that type that really is very, very, very self-evident? Like one-line inline
>methods. Ok, there aren't alot of those that are protected or private, but
>still, there are things that are almost as self-evident.

For interface stuff (public & protected) at least one short one-line
comment. For obvious private stuff, well, we're only better coders should
look at that anyway ;)

>Do we document standard accessor functions (ie, GetSomething(),
>SetSomething() and IsSomething()) ?

Yup. And if it's only to make the generated reference complete and
consistent.

>Do we document exactly what each parameter does? What if its self-evident?
>Like SetScore(ppSizeT score)...

//: Set the score

>suchs as accessors. Even accessors can from time to time have surprising
>behavior. Accessors are not always nessecarily just methods that return a

All surprising behavior has to be documented anyway.

>information. As an example, suchs a thing might effect the state of a
>cachebuffer.

? You mean some hardware or OS cache?

>We probably also can make documentation for stuff that is bound to change
>pretty soon not so comprehensive. That would be most of PenguinPlay, right
>now, I reckon.

Right. As long as is is comprehensively documented at release time, it's
fine.

>* What does each parameter do? (if any)

Unless it's obvious. You don't have to document on the parameter in 
void SetSize (ppSizeT NewSize);

>* What does the function do? (detailed) (if not already covered)

Unless it's obvious.

>+ other documentation that is related to this function/class/data (don't
>know if it is possible to get the documentation compiler to generate links
>like this)

Good question...

>Simple stuff is simple, easy and quick to document. Very complex stuff takes
>a little more time to document, but then, it should.

Right.


	Christian
--

Drive A: not responding...Formatting C: instead