One of the great benefits of picking up on Coffee on the 16th of this month, two days ago, has been that the onerous task of establishing a development enviornment was simplified by simply copying the CoffeeScript project structure.
Starting on the 16th, and starting with getting Vows to work for testing and
Expresso to work for coverage of JavaScript, I created beautiful literate
programming articles using docco which gave me an incredible sense of
accomplishment. I created an Node.js executable, created an npm installation,
provided for installation using git clone to ~/.node_modules using an
index.js, built everything using a Cakefile, and got started on designing a
project website in Jekyll.
This is as complete a project as I've ever released to open source.
There are parts of the structure that run counter to version control purity. The CoffeeScript checks in the generated JavaScript and generated documentation. I recall getting into an unproductive exchange with the create of Compass about the merits of checking in generated SASS. He believed it a sin to check in generated code, while I thought it was silly not to check CSS generated by Ruby into my Java project. Silly, but, I'm sensitive to fact that certian communities that hold programmers in low esteem if they check outputs into version control.
But, GitHub has features that are git based, like gh-pages. True, gh-pages has a Jekyll engine, so you can check in source and have it converted at check in, but it would never be able to generate Javadoc or RDoc or the like, and that is the sort of thing you'd expect to find on your project site, right?
CoffeeScript doesn't fetishize source control and does take advantage of GitHub features. The point that Jeremy makes, that I tried to make about SASS, was that, the faster that people get started, the more likely the adoption of the project.
However, I do like minimal change sets, so I created a project structure master does not have generated JavaScript to Docco. One of the cake tasks is to create a gitignore.
cake gitignore
And it will create the appropriate ignore based on the git branch. So for master the ./documentation directory is part of .gitignore, but for gh-pages it is not. After I've pushed the generated documentation a couple of times, I'm going to create...
cake publish:gh-pages
Which will flip over to gh-pages, merge master, cake docco, git push origin HEAD, then flip back to master. All made much easier because gh-pages is a superset of master.
For '~/.node_modules' or git checkout, there is a 'node_modules' branch which includes the compiled JavaScript. In this use case, the ./index.js file will be launched, so that file checks to see if the files exist, and if they don't, it prints out a nice long and descriptive error message telling people to switch branches to node_modules or cake compile.
Jeremy puts an index.html in the root so that he can use gh-pages to serve the CoffeeScript site. I wanted to have a nice site with some templating and I'd hoped to use _config.yml to move the site to ./site so that all the Jekyll bits were not in the root. Unfortunately, source is overridden by GitHub Pages.
Thus, to use Jekyll, you need _config.yml, _plugins and _layouts and the like in the root. That is quite cluttered.
I"d like a default CoffeeScript project page style, so that, when I complete my project I have my Docco documentation to document the source, but I have a CoffeeScript project page to document the API.
As an ex-Java programmer, I greatly appreciate Docco as a means to document the source code itself, and would hate to see that polluted with API documentation.
Javadoc was stupid stuff. I might have a Guice modules with dozens of bindings defined using the Guice binding DSL pretty much documenting themselves, right there, three lines below a tedious repetition of what would be obvious if only you could see the source.
The literate programming nature of Docco and CoffeeScript is something different, something good. It has made it very, very easy for me to learn CoffeeScript by reading programs (the pixel-ping.html example was powerful). This is a feature that would get erased by embedded API documentation.
If embedded API documentation were added, the source files would be working overtime. It is a challenge to keep the amount of prose proportional to the incredibly terse CoffeeScript code blocks already. I believe adding the sort of detailed descriptions necessary for API documentation to the source will run the legibility of the source.
Besides, CoffeeScript is weakly typed, so you don't get the benefits of API documentation generation, (or maybe you do, it is not as bad as JavaScript)
Rethink. Okay, maybe you can flag certain functions as public, and their signatures will be extracted, but documenting the source in literate style and documenting the API in Javadoc style are two tasks that are going to run counter to each other and the source files will do too much work.
API documentation needs to be accompanied by a lot of exposition and code examples. Embedding that stuff in the source, is painful. I'd much prefer some way to create that document separately.
Here's a flavor of overkill. This is not the purpose of this essay, just a thought.
Maybe, for the sake of having Javadoc/RDoc like documentation, we could have an interface definition language.
Then we could even take a tool based approach to testing the interface. At the very least ensure that the modules, when loaded, provide the classes and functions described. At the very most, use the IDL to compile assertions, pre-conditions and post-conditions.
Then you could attach the API docmentation to the IDL and create a tool that generates a function reference, glossary like documentation.
But the source code files are left to express and document the implementation.
As a programmer who is not a graphic designer, the Docco generated code is very rewarding and makes me feel that my code is beautiful.
It would be nice to at least have default Jekyll template to compliment the Docco, that looks like the Docco or CoffeeScript site. It can be Jeykll based, with Jeykll plugins, or it can be CoffeeScript based and derived from Docco.
But, then, the grand appeal of CoffeeScript will be a small community (soon to grow) with a great GitHub footprint for your projects and recipes to go from a blank repository to a fully documented project that publishes itself.