The styles and conventions used to document the Finexec scripts and definitions are
set out below.
The scripts are documented using the ~addons/docs/joxygen/joxygen.ijs addon package
which creates htm files from the script.
For details see: Joxygen
Example: category documentaion:Finexec Category: Basic Finance Example: script source documentation style: finexec/basicfinance/simple.ijs Example: script documentation: finexec/basicfinance/docs/simple.htm
The category documentaion provides: 1) details of the subject and tasks covered in the category 2) list of scripts in the category 3) list of definitions in the category
As a general style the Finexec scripts are stand-a-lone (ie. no dependencies) Any dependencies to other scripts are listed at the start of the script. Use the require definition to load any dependant scripts to aviod having to reload the script. The definitions from a script are loaded into the locale base unless otherwise indicated in the script. The documentation for the definitions in a script can be viewed by linking to a script. The scripts can be used for projects and jobs. The scripts can copied, modified and loaded into another locale for a project or job to aviod potential naming conflicts. View Source Script The source script can be viewed in Qt and JHS IDE front ends. eg: Qt IDE: open '~addoms/finance/finexec/basicfinance/simple.ijs' eg: JHS IDE:edit '~addons/finance/finexec/basicfinance/simple.ijs' Source Script Names Script names as general rule use lowercase. For example:~addons/finexec/basicfinance/simple.ijs Script Status Defined as: done: update: review: todo: dev:
Names
The naming style for verbs, adverbs and conjuctions is to commence with a lower case letter
and can be all lower case or camel case.
The naming style for nouns is to commence with an upper case letter and can be all upper case or camel case.
Documentation
Definitions start with NB.* and can have some or all of the following documentation details:
(Even for the most trivial or simple definitions.)
Name(type): type: (acvmdn) for/or adverb, conjunction, verb, monad, dyad, noun
Form: tacit or explicit
Depend: If required list any dependent definitions even if from the stdlib and script. eg: def/script
Description: What the definition is used for and if applicable an equation.
Note: Any special details.
Syntax: Details of how the definition is used and specification of the data inputs to the definition.
Left(L) and Right(R) arguments in the syntax to a definition have been enclosed in brackets eg:
definition(R)
(L)definition(R)
The brackets are generally redundant and are used for clarity.
Example: The examples can be tested to review the performance of the definition.
Definitions have two forms, tacit or explicit. Tacit definitions have no dependencies and are self contained only using J primitives. The adverb fix f. can be is used to create a fixed tacit. A tacit definition can be defined and used in an explicit definition. Explicit definitions are created with the verbs: 3 : 0 or 4 : 0 The Form of a definition (tacit or explicit) can be useful in deciding how to to use it or modify it for a project or job. The explicit form is generally easier to produce, read, debug and often useful for developing the tacit. The tacit form is produced as first choice if possible otherwise the explicit form is used. Explicit definitions are generally stand-a-lone but may include dependencies. Always check the documentation of the definition and source script. A tacit definition may also have an explicit form: zzz and zzz_E.
Where possible equations are provided for definitions in a script. Equations are in html files using the <math> HTML markup element. The equations are created using the MathType application. Some browsers may not support the <math> element and therefore equations will not be displayed correctly.