Documenting Goby Code

We use Markdown to document. All markdown syntax are supported.

Documenting Classes

All classes can be found in /vm directory. Each class is represented by a file. For example, you can find Integer class in integer.go file.

The class definition can be found with the type named as the filename or suffixed with "Object". The documentation for this class is right above this type. For example, Integer class is documented as:

// Integer represents number objects which can bring into mathematical calculations.
//
// ```
// 1 + 1 # => 2
// 2 * 2 # => 4
// ```
type IntegerObject struct {
  Class *RInteger
  Value int
}

Builtin classes are usually self-explanatory, but classes like JSON or Random might need more documentation and examples on how to use them.

Documenting Methods

Methods of a class are stored in an array, with its name prefixed with builtin and suffixed with Methods. For example, the name for Integer class is builtinIntegerMethods.

The Basics

Each method comes with two keys, Fn and Name. The document of a method comes right above Name. For example:

var builtinIntegerMethods = []*BuiltInMethod{
  {
    // Returns the sum of self and another Integer.
    Name: "+",
    Fn: func(receiver Object) builtinMethodBody {
      // ...
    },
  },
}

• Remember to leave one space after //.
• The subject is the method, so the sentence usually starts with a verb that describes this subject. For example, "Returns" describes the + method. Don't repeat the method name in the comment.

Code Block

We encourage you offer one or two examples for a method. Using markdown allows us achieve so easily.

{
  // Returns the sum of self and another Integer.
  //
  // ```ruby
  // 1 + 1 # => 2
  // ```
  Name: "+",
},

Several things to note:

• We don't have Goby syntax highlight for now. Use Ruby before we have it.
• Keep a blank line between the code block and description for readability.
• Use # => if your code got an output.

Parameters

We allow documenting parameters using the @param keyword:

{
  // Retrieves an object in an array using the index argument.
  //
  // ```ruby
  // a = [1, 2, 3]
  // a.at(0)  # => 1
  // a.at(10) # => Error
  // ```
  //
  // @param index [Integer] The position of the target object, starting from 0.
  Name: "at",
},

The pattern works like this:

• Each element is separated by a space.
• The first element after @param is the name of the argument.
• The second element is the class of this parameter.
• After that is description.
• A @param is skipped if no name & class specified.
• If multiple types are allowed for this parameter, use Object as its type.

For unlimited number of parameters, add *args as arguments:

{
  // Adds any number of Object to the receiver.
  //
  // @param *args [Object]
  Name: "push",
},

For block argument, add &block as argument:

{
  // Yields each element into the given block.
  //
  // @param &block [Block]
  Name: "each",
},

Returned Values

Returned values work like parameters but with some differences.

{
  // @return [Object] The retrieved object in the array.
  Name: "at",
},

• The first element after @return is its class.
• After that is description.
• A return is skipped if no class specified.
• If the returned value is possibly two or three types, list them all in multiple lines. If it is possibly any type, use Object. For example:

{
  // @return [Object] The object at the target position.
  // @return [Null] Returns a Null if no value is at the target position.
  Name: "index",
},

For now we only support one-line description for parameters and returned values, and no code block.

Class Links

The class names are converted into links, so instead of writing:

// Returns integer.

write:

// Returns a Integer.

The parser matches the names for classes so remember to capitalise them.

Unsupported Comments

Currently the documentation only supports // comments, but not /* */. The following comments will be ignored:

/*
  Integer represents number objects which can bring into mathematical calculations.
*/
type IntegerObject struct {
  Class *RInteger
  Value int
}