Beautifully Documented Code

When searching for a documentation system to use for Ubiquity, we looked at a number of tools. None of them particularly satisfied me; all the ones I saw required a build step to convert raw source code into formatted documentation, and I wasn’t very pleased with the typography of the generated content—though obviously the aesthetics were customizable through CSS, none of the default stylesheets left me dying to read the documentation I created.

I’ve always had these kinds of hangups when it comes to design; a lack of it repels me from some software that might otherwise be interesting or useful, while good aesthetics is part of the reason I’m drawn to a handful of projects like TeX that are truly elegant out-of-the-box. With this in mind, I decided to play around with creating my own simple code documentation system.

The result so far is here: a single-page JavaScript application that can be served from static files, which takes in raw JavaScript files and dynamically renders the documentation alongside the code in the reader’s browser.

The raw source code for the file being documented above just has chunks of comments that are marked-up in WikiCreole; when the parser runs into such a chunk, it renders it alongside the code it annotates using Ivan Fomichev and Chris Purcell’s JavaScript Creole 1.0 Parser.

The idea of using the documentation to annotate the code—or the code to annotate the documentation, depending on how you look at it—was inspired in part by some of the typography presented in Ellen Lupton’s excellent Thinking with Type, which I recommend to anyone interested in the field.

It’s nice not having a separate documentation build step: aside from making the process of writing and editing documentation quicker, it also lowers the barrier for entry to contributors since they don’t need to setup a toolchain. It also means that we get versioned documentation in every commit for free.

Right now there isn’t much else to the system; the only other feature I added is the auto-generation of quasimodal popup menus that link the names of XPCOM interfaces to their entries on XUL Planet and MDC. It’d be nice to have more features like this; other niceties would be an automatically-generated table of contents, JavaScript Doctests, search functionality, cross references to other code, and even the ability to fix code formatting errors in-page. For now, though, I need to focus on actually using this tool to document more code.

Speaking of which, Ubiquity code could definitely use more documentation—especially the APIs for command authors, which many developers would love to see. If you’re interested in helping out, please feel free to join us on ubiquity-firefox, #ubiquity on irc.mozilla.org, or email me directly at my first name at mozilla.com.

EDIT: Since posting this, I’ve spun-off this code into a small new project called Code Illuminated. Contributions are welcome; I’d specifically like to thank Sander Dijkhuis for his excellent work so far. If you’re interested in helping out, feel free to join the mailing list.

30 Replies to “Beautifully Documented Code”

  1. Nice documentation and I like the paradigm code annotating the documentation. Maybe the programmer will write a better and clear code for saving the documentation. 😉

    I am not sure if you are saving a step.

    In the live system you will have the minified scripts (without comments), so you will need providing a raw source code as documentation file: it is equivalent to the doc created in the build step. And this raw source code could not be the latest release of the source code (so it doesn’t matter if it is not minified), because the development release could be different.

    So it seems you have not a separate documentation build step, but you need always a separate “doc” file.

    Another consideration is about the annotation (and the related parser): I don’t know how much that annotation is supported.

    Maybe I am afraid about the paradigm change. 🙂

  2. Hi Atul.

    I think it would be interesting (as in “useful”) if you could post an example of the code prior to being rendered by your documentation utility. This way you could get the “before and after” and see the comments format (WikiCreole)

  3. This is Knuth’s Literate Programming, rediscovered in a limited fashion. LP goes back to the eighties, so it’s well developed but somehow lost momentum because it required an old-fashioned batch-like flow: the LP source was processed to create both the source code and documentation. The advantage of full-blown LP was that it had a rich set of facilities to cross-index and hyperlink the code. My personal favorite was breaking up the linear code into small chunks that could be ordered in a logical fashion, not by the demands of the implementation language (e.g. declaration chunks of .h files could be defined right next to the sections of .c code that defined the implementation).

  4. Thanks for reminding me how everything looks crappier in firefox on Linux. Compared to your render, what I see leaves something wanting. Let me go get my Windows box to see it in its proper glory.

  5. Actually, it doesn’t look good on Windows or Linux in any of {Chrome, Firefox}. It doesn’t render in IE.

    * Gray border around code actually only extends about 60% of the way across the code’s width.

    * On Chrome, the code’s font size is _much_ smaller than the documentation font, to the point of being unreadable without adjusting the sizes. When you do, the documentation font is too large.

    * As I mentioned, it doesn’t render in IE 7.

    * In Firefox, the code appears to be using some ugly, non-aa font rather than Consolas, my specified default for monospace fonts.

  6. @Alberto: Hmm, I guess I perceive the minified version of a program’s source code as an optional “build step” rather than the original, commented and documented source code. In some sense creating the minified version is almost like compiling, since the output isn’t very human readable. Perhaps I’m misinterpreting you, though?

    @Paulo: I linked to the raw source code with the Creole comments in my blog post, but you’re right that it probably would’ve been more instructive to show the input and output “side by side”, so to speak.

    @Przemek: Ah, yes, this does remind me of literate programming too… In fact it’s actually influenced by Jef Raskin’s “Humane Python”, which we used on the Archy project, and which was itself built on the philosophy of literate programming.

    @James: Er, yes, sorry about that. I foolishly assumed that not only does the reader use Firefox, but that they’re also viewing it on OS X. Will need to remedy that.

    @Pradeep: Cool! That looks like a useful library, too.

  7. “@Paulo: I linked to the raw source code with the Creole comments in my blog post, but you’re right that it probably would’ve been more instructive to show the input and output “side by side”, so to speak.”

    Hmmm… I think I overlooked the link to the raw code. That would make it one of those “my bad” kind of situations. Ok, to make up for that one I have two proper improvement suggestions:

    1. instead of forcing the declaration of the method names in the commentaries (E.g.: // ** {{{ Utils.reportWarning() }}} **), maybe you could up the automation a notch by automatically parsing the method names.

    2. It seems to me that you could improve the documentation readability if the method arguments stood out more. It seems to me that simply changing the font doesn’t cut it. Maybe using bold or underline or changing their colour.

  8. You might want to take a look at your own page with firefox on a windows box. The background doesn’t work so it is grey text on a brownish background. It looks fine in IE.

  9. I want to read this, but I can’t because it’s damn hard to read. Can you make it bg or font with different color please.

  10. Hi, Atul,

    This is an awesome library. And I understand that it wasn’t built in a Windows machine. I just wanted to add a bit to James’ comment about it not looking very nice in Windows, hopefully in a more helpful manner. No offence, James.

    1. Windows doesn’t have any of these fonts: monaco, andale mono, lucidatypewriter.

    2. I don’t know why, but you put Courier before Courier New. Maybe things are different on a Mac, but on Windows Courier New is *much* prettier than Courier.

    3. Courier New is Firefox’s default for monospace.

    So my suggestion would be to change your font-family line from this:

    font-family:monaco,andale mono,lucidatypewriter,courier,courier new,monospace;

    to this:

    font-family:monaco,andale mono,lucidatypewriter,monospace;

    This will look beautiful in a Mac, and in Windows it will be at least readable.

    James brings a very interesting point about “monospace” that is addressed with my suggestion, too. You, as the designer, have every right to choose your fonts, but please don’t choose substandard fonts over the browser’s default monospace 😉

  11. Curious as to why inventing a whole new way of documenting code? Was there a specific reason why or was there a flaw in trying to emulate javadoc (which phpdoc also uses)?

  12. following up to say, I am glad this exists, but from someone who writes a lot of PHP and Java and uses that documentation style extensively, it’d be nice to follow suit in this.

  13. Have to say this is by far the easiest to read documentation I’ve come across. (No problems on my mac of course) It is a great idea.

  14. Bery nice idea, the less steps from program to doc, the better!
    However, I’d like it to use standard JSdoc syntax instead of wiki, as the user gets IDE support when writing code.

  15. I second the IDE, a shell would be so much more useful than documentation when you have to debug your code.

  16. Since posting this, I’ve spun-off this code into a small new project called Code Illuminated. Contributions are welcome; I’d specifically like to thank Sander Dijkhuis for his excellent work so far. If you’re interested in helping out, feel free to join the mailing list.

  17. Hey Atul, this looks gorgeous. Have you gotten in touch with Eric Shepherd (sheppy) to talk about the automatic code documentation generation we use in Gecko/Firefox and see if there’s some way to move from that to this?

  18. Sounds like http://en.wikipedia.org/wiki/Literate_programming

    How about a script to generate documentation for Ubiquity commands automatically? So we can make an HTML page with a rel link to the commands.js, but then the visible content of the page (description of the included commands) is generated directly from the js using the same code that generates chrome://ubiquity/content/cmdlist.html

  19. I’m glad you found my library useful, because I couldn’t think of good use for it 🙂 Perhaps I will support it further now 😉 BTW, there has been a newer version with some features and minor bug fixes and unit tests (sic!) here: http://jscreole.svn.sourceforge.net/viewvc/jscreole/

    I added support for JSAN http://www.openjsan.org/ in the new version, as I had intended to, but it seems to me now, that JSAN is dead forever, though it is very sad indeed.

    Some bugs were fixed, as far as I remember they concerned inheritance (as far as you don’t create several different parsers, it shouldn’t matter) and escaping wiki code with tilda.

    Unit tests are very helpful for support and prove reliability of code.

    And yes, there’s some documentation in the new version too! 😉 I used POD for documenting my code, since it is standard for JSAN libraries, but perhaps you gave me another idea 😉

    I would be glad to know if there are any wishes for features to implement, e. g. for extra markup or whatever.

  20. First of all, I wish to thank you for this wonderful project. I think this is a very simple still powerful way to make documentation easier to write and understand.

    Since I really enjoyed your project and I am a hobbyist .NET programmer, I started a similar one specifically created for that Framework. It is still in early stages, but it is meant to a community effort, so all the interested persons can have a look at it on http://neatlydoc.codeplex.com/

    Again, thank you and many congratulations for your ingenuity!

  21. JSAN is not dead for ever, it is just that Casey West who started the project is gone from the project which is why it stagnated.

    The JSAN index is working again, people are building more modules and documentation. Me and some people from the Perl and Joose communities are working on JSAN again…

  22. I love it. Thanks for that.

    Big downside though: I think it’s a bad idea to use WikiCreole. It force developers to think about comments formatting.
    Instead you should use classic @tags and figure out automatically what is the appropriate formating.

    Compare:

    // === {{{ Function name }}} ===
    //
    // This function does that and that and needs these parameters:
    // {{{ param1 }}}: a string

    Versus:

    // Function name
    //
    // This function does that and that and needs these parameters:
    // @param {String}

Comments are closed.