Articles
Articles are single-page pieces that give a whirlwind tour of a specific topic.
They’re different from series, which go very in-depth, taking many detours.
oocdoc, Part 4 — sourcepath
In the previous article, We’ve built a nagaqueen-based tool that can parse one ooc file, detect class declarations and print its doc strings. Today, we’re making a bit of infrastructure for our app to support more sizable projects.
Source path and lib folders
Parsing a single file was a nice milestone, but it’s not nearly enough. We want to generate documentation for a whole project at a time: and since we’ll want to cross-link the various bits of documentation we generate, we’ll also need to parse the various dependencies (such as the ooc sdk, and any used library) so that we can resolve argument types and link them properly.
oocdoc, Part 3 — parsing
In the previous article, I gave brummi a go. However, we’ve seen that it still doesn’t fit our requirements: we need a tool that’s fast, easy to install and configure, produces beautiful and usable docs.
Yesterday I started building my own documentation generator, and in this series I’ll present the challenges I face and how I solved them. This might show a few ooc tricks, perhaps some software design, some good, some bad, but overall I hope it’ll be a good read!
The shortest ooc quine
A few days ago I posted an ooc quine. But while browing HackerNews, I found an even shorter one. The shortest!
Here it is, in its full glory
Can’t see anything? That’s an empty file. It will compile and run just fine. ooc doesn’t require a main function - you can just shove code in there that will run at the program’s initialization. If there’s none, no big deal! It’ll just not run anything.
An ooc quine
While preparing my next post about ooc documentation yet again, I stumbled upon an old ooc quine of mine. Here it is in integrality for your pleasure:
q := 34 as Char
l := [
"q := 34 as Char"
"l := ["
"]"
"for (i in 0..2) {"
" l[i] println()"
"}"
"for (i in 0..12) {"
" q print(); l[i] print(); q println()"
"}"
"for (i in 2..12) {"
" l[i] println()"
"}"
]
for (i in 0..2) {
l[i] println()
}
for (i in 0..12) {
q print(); l[i] print(); q println()
}
for (i in 2..12) {
l[i] println()
}
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.
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).
oocdoc, Part 1 — NaturalDocs
Documentation in ooc land has sucked for quite some time. The standard response is pretty much: “use the code, Luke!” — which is fine when doing small projects that don’t matter much, but not so when you want to get serious.
So when a newcomer, beoran, asked how to generate documentation, and later told us he got NaturalDocs to work, naturally, I had to see for myself how well it worked.
Experiments in happiness
If you’re a regular, you might’ve noticed the place has changed around a little. Thing is, I’ve been spending time playing around with a radical new concept: happiness.
The year and a few months that I’ve spent working for a start-up were actually a pretty gloomy time for me, both for professional and personal reasons. It took me a while to get out of this hole and start thinking positive again.
Isaac rubs his back on non-existent doors
Haven’t blogged in a while. Life’s fine, project are a-plenty, but I just wanted to make a more lasting post about one particular issue that struck me as funny when programming Paper Isaac.
Bugs, bugs, bugs
What’s infuriating when letting others play an early prototype is that you hear constantly the same things. Some bugs are non-trivial to fix, some you’re just not motivated to fix now… sometimes you just have your head elsewhere, gotta focus, or are elbow-deep in some other piece of code and the damn walls can wait.