Documenting DUCK

Having recently considered restarting work on my Dalvik compiler tools, I thought I should at least try and improve some of the documentation that accompanies the project, beginning with the example applications.

The examples are written in a Python-like language that I called Serpentine. Programs written in this language are syntactically valid Python source code, but they wouldn't run in a Python interpreter even if you had a set of replacement modules for all the Java and Android libraries. (As an aside, my brother wrote a partial set of compatiblity modules for the Java standard library as part of his javaclass project many years ago.) The incompatibility between the languages is intentional. I wanted to be able to write programs that would be represented using as few virtual machine instructions as possible and, since the virtual machine is designed for a statically-typed language with primitive types, I was comfortable with imposing restrictions on how the language uses types to make the compilation process as simple as possible.

It would be possible to implement more dynamic, Python-like types on top of the primitive types but this could lead to inefficiencies at run-time or, at the very least, a more complicated compiler. Since the overall goal was to have a language that resembled Python enough to make Android programming familiar to a Python programmer, implementing all the semantic features of Python is not really a priority, especially since programmers have to face up to the platform APIs at some point.

Inline Documentation

One of the other areas where I decided to experiment with non-Python-like behaviour is in the use of docstrings, the short text descriptions that follow the start of modules, classes and functions. These are handled specially by the standard Python parser so that they don't get mixed into the code that the CPython interpreter wants to run. However, when parsing code for other purposes, this can be a bit of a disadvantage. One thing I wanted to do was to interleave descriptive strings throughout a program and process them to create a document that combines text and source code. Having the docstrings stored separately from other nodes in an abstract syntax tree makes the task of doing this processing a bit more tedious since we need to work out where the original strings were in the source code.

The Mercurial repository for the project is currently residing on GitLab, which is less than ideal from a Free Software perspective. However, we can take advantage of the service's Markdown support to automatically render files marked up in this language. Since Markdown tends to be supported by other services and tools, we are not locked into this service and could easily migrate the repository elsewhere, processing the documentation differently if required. Since Markdown is not so different to reStructuredText, we could even just generate documentation using Sphinx with not too much effort.

The end result is that inline text from the examples is interleaved with the source code to produce text in Markdown format. When the contents of the repository are viewed in a browser, this text is processed and rendered as regular HTML by the hosting service, making it easier to read about the examples provided with the compiler.

Although I haven't used this approach for the compiler itself, I think that it might be interesting to try it. The style of documentation I am used to writing is focused on how programmers use library APIs, but documenting the internal structure of a project is a different kind of task. Perhaps I'll experiment with a combination of the two approaches to try and get the best of both worlds.

This document is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International license.