Rather than attempt to document the complete Evlan API on this web site, this page will show you how to retrieve documentation already included in the source code. The methods described here can be carried out directly from within the command client.

As a starting point, type "/help". This will give you a great deal of information on the interpreter's built-in commands. Note that in Evlan v0.3.3, there is a small mistake in this information: For the "/list" command, there should be no space between "/list" and the depth. For example, you would type "/list2" to list at depth 2. If you omit the depth (just type "/list"), a depth of 1 is used by default.

The "/help" command, if followed by an expression, will retrieve documentation regarding the result of that expression. For example, if you type:

/help Thread

you will receive information about the "Thread" module (which is one of the common Evlan modules which is automatically imported). You can retrieve information about an individual member of "Thread" like so:

/help Thread.make

This gives you documentation for the "Thread.make" procedure.

You will notice that the documentation for "Thread" does not list its contents, and the documentation for "Thread.make" does not list its parameters. This is because you can obtain this information trivially without need for the documentation. To see the contents of "Thread", type:

/list Thread

To see the parameters for "Thread.make", type:

Thread.make

These techniques work regardless of whether or not the author took the time to write documentation.

Unfortunately, as of Evlan v0.3.3, most of the API does not contain proper documentation. My plan is to fully document the most important modules for the next release, then decide whether or not to document the rest based on interest.

Documenting Your Code

Documenting your own code is easy. At present, the system is rather ad hoc, but the basic idea is that if you place a comment before a statement in a "where" or "object of" block, and that statement declares a function or an object, the comment will be attached to that function or object as documentation. For example:

MyModule where
   #This is documentation for MyModule.
   MyModule = object of
      #This is documentation for function1.
      function1 = (a, b) => ...
      #This is documentation for function2.
      function2 = x => ...

Text within a documentation block will be converted into paragraphs when it is later printed. This means that line breaks in the text will be removed. To separate paragraphs, leave a blank line between them (this blank line must still contain the # character to begin the comment). If you wish to insert text that should not be interpreted as paragraphs (such as sample code), indent that text. Indented text will not be considered part of a paragraph and will not be mangled.

At this time, documentation is implemented as a bit of a hack. Documentation comments can only be placed within "where" and "object of" blocks. They must precede a statement which defines either a function or an object. The statement cannot refer to a function or object declared elsewhere. Values other than functions or objects cannot be documented. Hopefully, these problems will be improved in future versions.