Question about typical API documentation format?

[RickJ]

Let's assume we are documenting several classes and that each class contains both class and object methods.  Let's also assume that each method will be documented with a title or headline and some descriptive text.  Also let's ignore the other elements such as the declaration, examples, etc.

Note: in the Ags script language "class method" is equivalent to "static function" within the bounds of a struct declaration.

What I would like to know what format the headline ought to be in and specifically what is the difference between the headline of a class method and the headline of an Object method?

For example the AGS documentation just uses ClassName.MethodName() for both class and object methods.  This seems to work out ok but there are very few (if any) class methods so there isn't much chance for confusion.   I realise that it all get's sorted out in the example code but still wonder if there shouldn't be a differentiation in the headline something like this:


6.2 ClassName.MethodName()   (class)   
The MethodName method does this that and the other thing.  ...


7.3 ClassName.MethodName()   (object)
The MethodName method does this that and the other thing.  ...


Any thoughts, observations, or opinions are welcome.   Thanks.

[monkey0506]

By "class" and "object" methods you are referring to "static" and "non-static" (member) functions of a class (struct), yes? Because in that case I suppose it would depend what language you're working with. For example AGS (like C++) uses the keyword "static". In the AGS documentation any functions which are static are defined as:

static Character* Character.GetAtScreenXY(int x, int y)

Whereas a non-static function simply doesn't have that keyword:

bool Character.HasInventory(InventoryItem *theItem)

So if the language you're using has a keyword such as that, then I believe it's sufficient to distinguish them in the documentation just as much as it is to distinguish them from each other right in the source code.

Otherwise I think what you've done there, just appending class or object to the end would work well enough.