grdoc and Object Oriented Languages

This page describes the tags and intended uses of those tags for using grdoc with an Object Oriented language. The two OOL's we are specifically considering here are C++ and perl5. java already has a good documenting system (javadoc, which inspired grdoc) and all the other OOL are for girly-men (joke; we simply just don't use em!).

The extensions we've made revolve around three important tags and tag interpretations as detailed below. Also, note that in the current release, none of this is implemented!

@class / @package / @struct

@class (and it's synonym @package) describe a class within your OO Lang. This class has the same properties as a routine (eg, it contains @var for member variables etc...) but it also has two important new tags

@method methodname method description @endmethod	This allows you to put a short description of a method in the class definition grdoc section. note, even if methodname is overloaded, you should only put this in here once, without arguments. The reason for this will be clear when you read about the new use of @routine below.
@inherits class, class, class	Inherits from other classes

Note that you could use @class to document structures in C code (and even fortran if you're brave and clever). Thus, the keyword @struct is a synonym for @class. However, it doesn't make much sense to have member functions of a structure, so don't use @method or @inherits in a struct!

@seeclass / @seepackage / @seestruct

These do exactly what you'd expect them too!

@public / @private / @protected

These are three boolean keywords which can be associated with an @var declaration in an @class, or with an @method declaration.

The new meaning of @routine

In an OOL, we use @routine to document a member function where it is written. However, the name of the member function has an important meaning. Namely;

  @routine foo::bar(arg,list)

foo indicates the package. bar indicates the routine name (which would previously have been all that was in the @routine spec) and the arg list differentiates this method from others (and is option). Note you can specify @public etc... in your @routine if you want.

grdoc's behaviour with the OOL extensions

grdoc will write classes just like it currently writes files. For each @method it will see if there is an @routine existing whose name matches that @method. If there are none, the @method will simply be displayed with the blurb. If there is one, the @method display will link with the arg list. If there are multiple ones, grdoc will create a list of all the overloads of the method underneath the short description, complete with argument list.

Also, grdoc will make an inheritance tree.

Finally, in the more distant future, grdoc will include routines from the inherited classes which are not implemented in your current class, and display them in the current class as inherited. But don't hold your breath.

Once John gives me an example grdoced c++ code, there will be an example here!