Language Documentation

You must provide documentation for your language. You have total control over the format of this documentation; for example, you could create a website for it with links to different parts (GitHub has free web hosting and makes this relatively easy), create a video, or create a more traditional document. No matter the format you use, your documentation must cover the following:

• Why this language, and why this language design? What kind of problems might this language solve, and why was it designed this way? It's perfectly acceptable to say that the design is arbitrary. Similarly, it's fine to say that some component of your language was intentionally restricted to make implementation easier - real languages do this! Overall, I'm interested in better understanding your design and thought process.
• Code snippets in your langauge highlighting features and edge cases, along with relevant explanations. These snippets should give a general sense of what your language provides, and what sort of restrictions your language has. It's ok, and even encouraged, to show snippets that don't work correctly or are otherwise strange; no programming language is perfect, and it's best to point out flaws upfront rather than have a user (or me) find a flaw after some digging. I'm not expecting perfection.
• Known limitations. What can your language not do? Is there anything particularly hard to do with your language? This may be redundant with your code snippets, depending on how detailed your snippets are.
• Knowing what you know now, what would you do differently? If you had to start the project all over again from the start, is there anything that you would do differently? For example (no need to answer any of these specifically; this is just to get you thinking about possibilities):
  • Would you design anything differently?
  • Would you choose a different development tool (e.g., editor, build environment, communication method, etc.)?
  • Would you choose a different target language?
  Overall, I'm interested in the sorts of lessons learned during the development.
• How do I compile your compiler? In most cases, this can be copy/pasted directly from your README.
• How do I run your compiler? In most cases, this can be copy/pasted directly from your README.
• Formal syntax definition. In most cases, this can be copy/pasted directly from your language design proposal. It's ok if the syntax you provide is left-recursive.

Your documentation can include more information than the above if you so choose, but it must cover the above elements.

In terms of the size, there are no hard minimum or maximum sizes. That said, I would expect that you'd need at least two pages to cover everything, and that you're probably going into too much detail if you need more than ~20 pages.

Internally, I will use this documentation to assist in the grading process. The documentation is your opportunity to guide me through what you've done, and to point out both the good and the bad.

Examples

Both of these examples are from prior versions of the course, and are particularly good at what they do.

• JK-Java
• JavaCoop