oocdoc, Part 2 — brummi
👋 This page was last updated ~12 years ago. Just so you know.
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!
Here's another article just for you:
When rustc explodes
One could say I have a bit of an obsession with build times.
I believe having a “tight feedback loop” is extremely valuable: when I work on a large codebase, I want to be able to make small incremental changes and check very often that things are going as expected.
Especially if I’m working on a project that needs to move quickly: say, the product for an early-stage startup, or a side-project for which I only ever get to do 1-hour work bursts at most.