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 & Returned Values

We allow documenting parameters and returned values using the @param and @return keywords:

{
  // 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.
  // @return [Object] The retrieved object in the array.
  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.

Also:

• A @param is skipped if no name & class specified.
• @return does not need a name. You only specify its class.

For now we only support one-line description for a parameter, and no code block.

Don't

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
}