Notation used in Ruby API documentation
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
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.
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.
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.
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
[iter] RdbReference each_reference:
An iterator called "each_reference" delivering RdbReference objects.
[event] void layoutAboutToBeChanged:
A parameterless event called "layoutAboutToBeChanged".