Omnis Technical Note TNID0003 October 2006

Documenting your Omnis code

For Omnis Studio 3 or after.
By Andreas Pfeiffer

Code documentation is very important, especially in a project involving multiple developers or any long term development project that will requires updates and maintenance. However the task of adding documentation is repetitive and time consuming, so often it can be neglected altogether. But you can solve this problem with only a few lines of code.

Ideally each Omnis method that you write should contain a few comments at the beginning, such as the name of the developer and the date when the code was added. Since this is always the same, we can create a menu containing a small method and assign a menu shortcut (e. g. Ctrl-M) so it is easy to activate when you are coding in Omnis.

For this purpose it would be best to create a new library and place it in the Startup folder of your Omnis installation. Then in the library create a menu (e.g. mDocumenter) with one menu line. In the properties of this menu line declare the appropriate shortcut key so that you can call the code behind this line with the keyboard shortcut. Then in the Startup task of your library, add a command to install the menu when the library is opened. You can do this using the command Install menu mDocumenter in the $construct of the Startup task. Because the library is placed in the Startup directory, the menu will now be installed by default, so the shortcut will always be available.

Next you need to add a bit of code behind the menu line. Enter the code in the $event method of the menu line. We can assume that the method editor will be open when this method is called. A comment line starts with a semicolon, so we begin the code with:

Queue keyboard event {ctrl-; Tab Tab Tab}

Alternatively, you can also record the events with the "Start recording" and "Stop recording" buttons when entering the Queue keyboard event command. The three tabs are necessary to set the focus at the right place for the next entry.

Declare a local variable buffer and enter the following code:

Begin text block
Text: [sys(3)] ;; company name from the serialization data
Text: - [sys(4)] ;; your name
Text: - [jst(#D,'D:CY-M-D')] ;; the current date
End text block
Get text block buffer
Copy to clipboard buffer
Standard menu command *Edit/11004 {Paste}

Of course you can customise the values included in the text block to meet your own needs. The trick is that a variable is filled with values, then the content of this variable is copied to the clipboard. If the focus is at the correct place, the last command will insert the content of the clipboard.