Documentation

Documenting Methods, Classes, and Variables

Ctalk allows you to add publicly visible comments to methods, classes, and instance and class variables. These comments are different than comments within the code that may have meaning only for specific routines

If you want to add documentation for a class, Ctalk allows documentation string is class declarations (see below). See ClassDocStrings.

You can also document instance and class variables. See VariableDocStrings.

When documenting methods, Ctalk recognizes both C-style comments and C++ comments.

In addition, Ctalk recognizes a character string at the beginning of a method or function as a public documentation string, and it adds a few rules for comments and documentation strings that make it easier to describe methods when browsing the class library.

Basically, if the method contains a comment or documentation string at the start of a method or function body, then that style of comment is used as the method’s public documentation when it is referenced by other programs.

MyClass instanceMethod myMethod (Object myArg) {
  /* Using a C-style comment at the start of a method body,
     or a series of C-style comments, makes those comments 
     available as the method's public documentation. */
  /* The public documentation can span several comments if the
     comments appear before any lines of source code. */

     Method body...
 

  /* That allows you to add (perhaps temporary) comments elsewhere
     in the method that do not appear as part of the method's
     public documentation. */

     More lines of code...

}

MyClass instanceMethod myMethod (Object myArg) {
  // A series of C++ comments before the first line of
  // code also can appear as the method's public 
  // documentation.

     Method body...

  /* A different style of comment anywhere else within
     the method does not appear in the method's public
     documentation. */
}

MyClass instanceMethod myMethod (Object myArg) {
  "A character string at the start of the method also gets
   interpreted as a public documentation string."

   Method body...
}

The Ctalk libraries contain several methods that can be useful when printing documentation. Particularly, the method methods (in Object class) and methodSource (in Application class) can retrieve the names of the methods in a class and their source code, and the method tokenize (in String class) can split the source code into tokens, which you can then process.

Here’s a simple application that retrieves a method’s source code and splits it into tokens.

int main () {

  Application new app;
  String new methodStr;
  List new tokens;
  
  /* The first argument to methodSource is the class name, and
     the second argument is the method name. */
  methodStr = app methodSource "Application", "methodSource";

  methodStr tokenize tokens;

  tokens map {
    printf ("%s ", self);  /* This example simply prints the method's
                              tokens, but you can perform any processing
                              or formatting that you want here. */
  }
  printf ("\n");
}

If you want only the prototype of the method; that is, the declaration and the argument list, feed the output of methodSource to methodPrototypes, which is also in class Application. The methodPrototypes method takes a string with the source code of a method or methods as input, which means you can also extract all of the prototypes of a class library.

int main () {

  Application new app;
  String new src;
  String new prototypes;

  src = app methodSource "Object", "basicNew";

  prototypes = app methodPrototypes src;

  printf ("%s\n", prototypes);

}

There are a few caveats:

The methods method is designed to be quick, so it only finds methods whose declaration appears on one line. If you prefer method declarations spread over several lines, you can read the entire class file using readAll (class ReadFileStream). See ReadFileStream. Then you can tokenize the entire class file at once, which disregards any line formatting, although tokenizing an entire file takes considerably longer.

Also, The methodPrototypes method does not do any special formatting; it simply collects the prototypes into one String object.

Class Documentation

Ctalk also allows you add documentation to class declarations. The declaration syntax allows you to add an option character string between the class name and the closing semicolon. The syntax of a class documentation is the following.

superclassname class classname <docstring>;

For example, here is the class declaration of WriteFileStream which contains a documentation string.

FileStream class WriteFileStream   "Defines the methods and instance 
variables that write data to files. Also defines the class variables 
stdoutStream and stderrStream, which are the object representation 
of the standard output and standard error streams.";

The classdoc program can print the documentation string of a class if it provides one. The classdoc(1) manual page provides more information.

Instance and Class Variable Documentation

You can add an optional documentation string to an instance or class variable’s declaration by enclosing the text within quotes immediately before the final semicolon.

WriteFileStream classVariable stdoutStream
"Defines an object that contains the value of the system's standard output";

The main thing to watch out for is, syntactically, a documentation string could be mistaken for a variable’s initial value if one isn’t included in the definition. For example, this definition uses a character string as its initial value.

ObjectInspector instanceVariable promptString String "> ";

So in this case, if you wanted to add a documentation string, you would also need to include an initial value, otherwise the documentation string would be mistaken for the variable’s value.

                                                      /* Incorrect! */
ObjectInspector instanceVariable promptString String      
"The string that is displayed as the object inspector's   
prompt";

Instead, you need to add both an an initial value, and the documentation string.

                                                           /* Correct. */
ObjectInspector instanceVariable promptString String "> "
"The string that is displayed as the object inspector's
prompt";