AutoCoda

Note: This page contains quite a few claims about AutoCoda, my latest scheme for a mechanized documentation system. Although I hope that at least some of the ideas will be implemented, at this point they are all highly speculative.

As the name implies, AutoCoda is an automated system that generates a coda (ie, follow-on document) containing information (eg, documentation, explanation, index, visualization) about a development project:

Coda (noun) - something that serves to round out,
conclude, or summarize and usually has its own interest

-- http://www.merriam-webster.com/dictionary/coda

Like YARD and some other mechanized documentation tools, AutoCoda accepts both human- and machine-generated information, including:

• human - assertions, comments, metadata, tags, etc.
• machine - results of static and/or dynamic code analysis

Initially, Clojure is the target language; Clooj and Light Table are the target deployment platforms. However, other languages and platforms are not excluded.

Goals and Approach

AutoCoda integrates and stores any available information on a code base, then provides high-level ways to query and display the information. So, for example, it should be able to produce diagrams showing various relationships between functions, state, etc.

Infrastructure

The initial infrastructure is still speculative, but it is likely to include most of the following:

• Clojure - Lisp variant for Functional Programming
  • C2 - D3-like visualization tool
  • Clojail, JVM Sandbox, etc. - sandboxing
  • Clooj - small, simple Clojure IDE
  • core.logic - Logic Programming
  • Lamina - logging
  • Light Table - coding work surface
  • Scape - static code analysis
  • Sleight - program transformation

• assorted web-based user interface and visualization tools
  (eg, CSS, D3, HTML, JavaScript, jQuery, SVG)

• Datomic - deconstructed, Clojure-inspired database
  (including the Datalog query and rule language)

• Sigma Knowledge Engineering Environment, SUO-KIF, SUMO, etc.

Target platforms

It seems appropriate to target multiple presentation platforms, both for convenience and to flush out portability issues. At present, I'm looking at starting with Clooj and/or Light Table, with thoughts of supporting both in the future.

Both platforms are open source, which encourages collaboration and experimentation. They also appear to play nicely with HTML5, so web-based tools such as D3 and jQuery should fit in well. If you have other target platforms to suggest, please get in touch.

Clooj

Arthur Edelstein describes Clooj as a "small, simple IDE (integrated development environment) for the Clojure programming language". This is true, but extremely modest.

Arthur is using Clooj as a test bed for access to Clojure archives, libraries, and functions. He is making important contributions in making functions easy to find, inspect, load, and use. This video presents a nice summary.

Light Table

Light Table is Chris Granger's interesting and ambitious project to provide "a work surface to code on". As I understand it, this will be a deconstructed and re-imagined IDE where multiple tools share a large display window, code base, etc.

Light Table could support an interesting ecology of cooperative tools. AutoCoda could provide some useful tools to this ecology, supporting code and library examination, etc.

Architecture

AutoCoda aggregates (harvests and collects) information on archives and projects, then makes the information conveniently available to developers. So, the high-level architecture (and context) look like:

Harvesting can be opportunistic, using either static or dynamic techniques to collect any information that looks "interesting". Using Datomic and/or other graph-based storage infrastructure, we should be able to support arbitrary queries into the collected information. Using HTML5 technology (eg, C2, CSS, D3, SVG), we should be able to present the results in a navigable and understandable manner.

Starting Points

• Arthur Edelstein has created Clooj and used it to explore notions in accessing Clojure libraries.

• Jonas Enlund has created Scape, a static code analysis tool for Clojure that emits Datomic transactions.

• Rich Hickey has created codeq, a Datomic-based tool that analyzes Git repositories and generates a graph of "code quanta" (eg, functions).
  • Google Group
  • GitHub page
  • Rich Hickey Podcast

• Zach Tellman has created trace-playground as a testbed for using Sleight and the Lamina trace mechanism to instrument Clojure code.

Related Work

• CodeViz - call graph generation utility for C/C++

• SPARQLy Ruby - SPARQL endpoints for RubyGems metadata

• clj-doc - documenting Clojure code

• Clojure Atlas - interactive UI for Clojure docs and source code

• ClojureDocs - community-powered documentation and examples

• Learnable Programming - awesome ideas on code presentation

• Codox - generating API documentation from Clojure source code

• Marginalia - Docco variant for Clojure

---

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!