oocdoc, Part 2 — brummi
👋 This page was last updated ~13 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!
Did you know I also make videos? Check them out on PeerTube and also YouTube!
Here's another article just for you:
A terminal case of Linux
Has this ever happened to you?
You want to look at a JSON file in your terminal, so you pipe it into jq so you can look at it with colors and stuff.
That’s a useless use of cat.
…oh hey cool bear. No warm-up today huh.
Sure, fine, okay, I’ll read the darn man page for jq… okay it takes
a “filter” and then some files. And the filter we want is.. . which, just
like files, means “the current thing”: