fasterthanlime

May 23, 2013 3 min #ooc · #programming

oocdoc, Part 2 — brummi

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.

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.

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!

Comment on /r/fasterthanlime

Here's another article just for you:

A new website for 2020

Jun 26, 2020

1 hour 3 min #announcement · #rust · #ftl-infra

Hi everyone. Has it been two months since I last posted something? Yes it has!

That seems like a nice round duration, so let's break the silence with a few announcements.

I have a new website

If everything goes well, you're on it right now.

Does it feel okay? Take a minute to accustom yourself to your new surroundings. Identify potential sources of fresh water. Gather some supplies with which to fashion a makeshift shelter.

Read more