2 min
oocdoc, Part 2 — brummi
👋 This page was last updated ~12 years ago. Just so you know.
Thanks to my sponsors: Marco Carmosino, Aleksandre Khokhiashvili, Raphaël Thériault, Josh Triplett, Kyle Lacy, Vincent, Matt Jackson, ACRL, David Barsky, Antoine PESTEL-ROPARS, Lyssieth, Berkus Decker, Mario Fleischhacker, Egor Ternovoi, Mikkel Rasmussen, Stephan Buys, Andrew Neth, Guilherme Neubaner, Matthew T, Geoffrey Thomas and 267 more
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:
A dynamic linker murder mystery
23 min
I write a ton of articles about rust. And in those articles, the main focus is about writing Rust code that compiles. Once it compiles, well, we’re basically in the clear! Especially if it compiles to a single executable, that’s made up entirely of Rust code.
That works great for short tutorials, or one-off explorations.
Unfortunately, “in the real world”, our code often has to share the stage with other code. And Rust is great at that. Compiling Go code to a static library, for example, is relatively finnicky. It insists on being built with GCC (and no other compiler), and linked with GNU ld (and no other linker).