NLDoc

[ Back ]

NLDoc is a program that was written just to make it easier to document the libraries in NaaLaa 6. It extracts information from comments in a NaaLaa source code file and turns it in to a HTML document. It was inspired by Doxygen but is, of course, a pale half-functional shadow compared to it.

Running the program

You can run NLDoc by double clicking its icon or from the command prompt. If you start it by clicking, it will open a file dialog, from which you can select a NaaLaa source code file. If you use the command prompt you pass the path to and name of your source file, like:

NLDoc my_program.txt

On success it will generate a .html file with the same name as the source file.

In the NaaLaa editor, you can run NLDoc for the current source file by selecting "NLDoc..." from the Tools menu.

How to comment your code

Here follows a short example program:

rem /**
rem @title An NLDoc example
rem @file example.txt
rem @version 1.0
rem @author John Master
rem @brief Just an NLDoc example.
rem
rem This example shows all tags that you can use when generating HTML
rem documentation from NaaLaa source code. It can be a usefull thing
rem when writing code (like libraries) that other people are meant to
rem understand without having to look at the source code.
rem */

rem Declare some constants. No, NLDoc doesn't care about normal
rem comments.
constant:
  rem /**
  rem @title Letters
  rem The letter A.
  rem */
  LETTER_A$ "A"
  rem /**
  rem The letter B.
  rem */
  LETTER_B$ "B"
  rem /**
  rem @title Numbers
  rem The number one.
  rem */
  NUMBER_ONE 1
  rem /**
  rem The number two.
  rem */
  NUMBER_TWO 2

hidden:

rem Some sub routines under two different titles.

rem /**
rem @title Letter access
rem @brief Get letter A.
rem
rem This is an advanced function that returns the letter A as a string.
rem
rem @return The letter.
rem */
function GetA$()
  return LETTER_A
endfunc

rem /**
rem @brief Get letter B in lower- or upper-case.
rem
rem This function returns the letter B either as an upper- or
rem lower-case string.
rem
rem @param lowercase True for a lowercase letter.
rem @return The letter.
rem */
function GetB$(lowercase)
  if lowercase
    return lower(LETTER_B)
  else
    return LETTER_B
  endif
endfunc

rem /**
rem @title Number printing
rem @brief Print one or one plus ten.
rem @param plusTen True for writing one plus ten.
rem */
procedure PrintOne(plusTen)
  if plusTen
    wln NUMBER_ONE + 10
  else
    wln NUMBER_ONE
  endif
endproc

rem /**
rem @brief Print one, one plus ten or one minus ten.
rem
rem Output the number one, one plus ten or one minus ten. Please note,
rem that you can also output one plus ten minus ten, but that's
rem completely pointless since it equals one.
rem
rem @param plusTen True for writing one plus ten.
rem @param minusTen True for writing one minus ten.
rem */
procedure PrintTwo(plusTen, minusTen)
  value = NUMBER_TWO
  if plusTen then value = value + 10
  if minusTen then value = value - 10
  wln value
endproc

And the resulting HTML file looks like this.

There's not much more to it. Every comment section meant for NLDoc starts with rem /** and ends with rem */. Most of the tags are optional.

[ Back ]