oocdoc, Part 2 — brummi
May 23, 2013
3 minute read

In the previous article, we saw how to use NaturalDocs, a language-agnostic documentation generator. Today we’ll see how to use brummi, a tool specific to ooc, written by Friedrich Weber.

Generating .json files

The first step to generate docs using brummi is to use rock, to generate a set of .json files describing the code. The --backend command-line option allows to select which backend you want rock to use (the C backend is the default).

rock –backend=json –outpath=../brummi-doc dye/core.ooc -v

In previous versions of rock, you could do what we call a libfolder compilation: compiling all .ooc files in a folder, recursively. However, to accomodate for various workflows including using ooc on android, that functionality is currently stubbed. So for now we’re using a main file that includes all other files.

Once that command is completed, ../brummi-doc will contain a set of .json files that look like this:

{
  "entities": [
    "File",
    {
      "type": "class",
      "tag": "File",
      "token": [703, 4],
      "genericTypes": [],
      "version": null,
      "fullName": "io_File__File",
      "doc": "\n   Represents a file/directory path, allows to retrieve informations like\n   last date of creation/access/modification, permissions, size,\n   existence, content, type, children...\n\n   You can also create directories, remove files, read their content,\n   copy them, write to them.\n\n   For input/output (I/O) beyond 'reading to a String' and\n   'writing a String', see the FileReader and FileWriter classes\n\n   :author: Pierre-Alexandre Croiset\n   :author: Friedrich Weber (fredreichbier)\n   :author: Amos Wenger (fasterthanlime)\n ",
      "name": "File",
      "abstract": true,
      "final": false,
      "members": [
        [
          "init",
          {
            "type": "method",
            "tag": "method(File, init)",
            "extern": false,
            "modifiers": [
              "final"
            ],
            "token": [ 703, 4 ],
            "genericTypes": [],
            "version": null,
            "doc": "",
            "unmangled": false,
            "fullName": "io_File__File_init",
            "name": "init",
            "isThisRef": false,
            "returnType": null,
            "arguments": []
          }
        ]
      ]
    }
  ]
}

The data contained in those JSON files is very detailed and allows a documentation generator to operate solely from them, without resorting to the source code!

However, I don’t really like this output - it’s very verbose, I’m sure the information could be stored in a simpler and more compact way. The reason the data is formatted as such is that it was supposed to be fed to Sphinx, a python doc generator.

Launching brummi & results

After following the instructions on brummi’s homepage for installation, just create a short and sweet config file, like so:

{
  "ooc_path": "brummi-doc",
  "out_path": "api"
}

Run it:

brummi config.json

And here’s what you get:

No CSS is generated by default, so of course it’s very primitive! There’s also no search, no index, just pure unadulterated docs. Interesting experiment in minimalism but not very usable.

Next time we’ll see how we can build a tool that understands ooc, to eventually generate docs for us. Stay tuned!