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:
- Datomic - deconstructed, Clojure-inspired database
(including the Datalog query and rule language)
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).
- CodeViz - call graph generation utility for C/C++
- ClojureDocs - community-powered documentation and examples
- Codox - generating API documentation from Clojure source code
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!