Tonto | ||
---|---|---|
<< Previous | Next >> |
The ability to make use of a package effecitively depends critically on the available documentation.
Since TONTO is primarily aimed at programers, the documentation is geared toward them.
The documentation is comprised of two parts---the short and long documentation. Both parts are extracted directly from the foo code. The short documentation is comprised of routine names with their documentation and variable declarations immediately afterwards; data components are also documented in a similar style. The body of the routine is not displayed. The long documentation is comprised of the entire foo code.
In both the long and short documentation, it is possible to to traverse the call-tree by hyperlinks, simply by clicking on underlined items. This can save much time when learning or remembering how an algorithm works.
Although both data and routines are accessed in the same way, by a dot notation, the documentation distinguished by colour those that are data (in green), and those that are routines (in red). Since efficiency is a prime goal of TONTO, it is hoped that the presence of many "red" routines in a hot loop would warn the programmer of any efficiencies.
A well written TONTO routine is short, and has a clear purpose which is reflected in its name. In order that the purpose of the routine is quite clear, its name can sometimes be quite long, and it will often use the underscore character. We hope that most routines in TONTO are well written.
There are a few other essential conventions: specifically, the first argument to every routine has the name self and is of the same type as the module it belongs to. In this way, the language is very similar to Python, for example.
The self variable is not explicitly seen in the documentation, or the foo code but its presence can be inferred by entities which begin with a dot, e.g. .name is the component name of the self variable.