Documentation

["Bjarke Hammersholt Roune" <asmild@post6.tele.dk>]

(everything here is, of course, IMHO)

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?

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
data-members (ie, not methods, but something like int m_count) ? Do you need
to do something special to get this documentation compiler to get that this
comment is really documentation and not just a comment?

Is this ok:

/*
 This is documentation on class ppSomeClass.
*/
class ppSomeClass
{
public:
    /*
        This is documentation for ppSomeClass::DoSomething()
    */
    void DoSomething();

    /*
        This is documentation for ppSomeClass::m_someInt
    */
    int m_someInt;
};

void ppSomeClass::DoSomething()
{
}

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

How do we comment? Do we set up precondition/postcondition rules? Do we
mention all exceptions that could be thrown by a function? Do we mention if
a function does memory (de)allocation or if it could potentially cause a
reallocation of something?

What about protected and private stuff? Do we document that? If not, then
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
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,
I'm not so certain about)

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.

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

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

If we are going to be documenting the source (as we are), we might aswell
agree on how to do it. There is no reason not to.

I think we should document everything, even things that are self-evident,
suchs as accessors. Even accessors can from time to time have surprising
behavior. Accessors are not always nessecarily just methods that return a
datafield of a class. They might also do some computing to get the requested
information. As an example, suchs a thing might effect the state of a
cachebuffer.

I also think we should document protected and internal stuff (depends a
little on its nature, though). We might want to have some way of excluding
this stuff, so we can build a seperate documentation for people who doesn't
care. Protected stuff IMHO does not need to be as comprehensively documented
as public stuff, however.

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.

This is a draft of what I think we should document, in this order, even if
it is kind of obvious (all of these of course does not apply to everything.
Functions with no a void return value of course does not document its return
value):

* What does the function do? (abstract)
* What does each parameter do? (if any)
* What is the special restrictions on when this function can be called /
this class can be used / this data can be accessed? (if any)
* What does the return value mean? (if any)
 * What exceptions can be thrown? (if any)
* What is the success behavior? (if not already covered)
* What is the failure behavior? (if not already covered)
* What does the function do? (detailed) (if not already covered)
+ Miscellanous stuff that hasn't been covered
+ 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)

This migth seem a bit too comprehensive. It migth also seem like something
that will taker FOREVER to do. But all of this information will not need to
be specified for every function.

Many functions don't throw exceptions. Many functions has no return value.
Many functions does not have any need to have miscellaneous notes attached
to them. Many functions do not take any arguments. Many functions are so
simple they do not need to be documented with a detailed explanation, as
there isn't any. Many functions do not have failure behavior.

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

IMHO, documentation is supposed to be so good and comprehensive so as to
make it unnessecary to look at the source code, except if one is curious, or
very consearned about performance of key parts of ones code.

What does everyone think?