Notation used in Ruby API documentation

Introduction

The documentation of the Ruby API is derived from the C++ declaration of the specific methods. Hence the notation deviates somewhat from the usual documentation of Ruby methods. In particular the following differences are noteworthy:

  • "Static" methods are "class methods":

    The C++ term "static" refers to methods available within a class without requiring an object. In Ruby, the term "class method" is commonly used to refer to such methods.

  • Different flavors of object arguments:

    In C++ there are references, pointers and objects passed by value. In Ruby there are only references. RBA maps the C++ concepts to ruby by allowing the "nil" value only for pointer arguments. Pointer arguments are specially marked in the documentation.

  • There is "constness":

    C++ has the concept of "const" methods and arguments. In C++, an object reference can be "const", which means that the object behind such a reference cannot be modified. A "const" method is a method which can be called on "const" object reference and such a method may not alter the state of the object.

    A method can have "const" reference arguments which means that objects passed through such arguments are not modified by the method. Such arguments are also said to have "in" semantics. Hence, "const" references can be passed to such arguments. In Ruby there is no concept of "constness" or "in" parameters. Every method is allowed to alter the state of the object it is called on and pf the objects it gets as arguments. In that sense, C++ allows specification of a more constraint "contract" between caller and method that is called. RBA emulates constness in Ruby to some extent and it may disallow calling non-const methods on const references or passing const reference to non-const arguments. Return value can also be const pointers which means that the object returned cannot be modified.

  • Strong typing:

    In C++, arguments and return values are strongly typed. RBA will check the arguments passed to a method and convert them properly. Hence the type of argument is important. "int" type arguments may not be passed strings for example.

    The type system if C++ is also somewhat more restricted: the value range of an integer argument is limited and for example there are unsigned types which cannot be passed negative values. Hence the type of an argument is noted in the documentation. A particular return type is "void" which basically means "no value returned". Strong typing extends to object references and RBA checks if an argument can be converted to the object required.

  • Virtual methods:

    In C++, a method must be virtual before it can be reimplemented by a derived class. In Ruby all methods are virtual. Since reimplementing a non-virtual method does not have any effect in RBA, virtual methods are marked as such.

General layout of the documentatation

The documentation states the following methods (in that order):

  • Public constructors
  • Public methods
  • Public static methods and constants
  • Protected methods (static, non-static and constructors)
  • Deprecated methods (protected, public, static, non-static and constructors)

Deprecated methods are listed for reference only. Use of such methods or constants is not recommended because they might be removed in the future.

Examples

Here are some examples for method documentations (signatures):

  • [virtual] bool event(QEvent ptr arg1):

    A virtual method called "event" returning a boolean value (Ruby "true" or "false") and expecting one argument (a pointer to a QEvent object). "ptr" indicates that the argument is a pointer, "arg1" is the argument name.

  • void add_reference(const RdbReference rdb_ref):

    A method without return value which expects one parameter. The parameter must be a reference to the RdbReference object. The reference must not be nil since it is not a pointer, but can be a reference to a const object. The name of the argument is "rdb_ref".

  • [const] unsigned int num_items:

    A parameterless const method called "num_items" that delivers the number of items as an unsigned integer value.

  • [iter] RdbReference each_reference:

    An iterator called "each_reference" delivering RdbReference objects.

  • [event] void layoutAboutToBeChanged:

    A parameterless event called "layoutAboutToBeChanged".