Crystal 0.5.6 has been released!
The most important feature of this release is the incluson of a prelimiary
that generates automatic documentation. Now you can browse the API docs for the standard library.
We will polish and improve the style with time, but at least it has lots of small nice features:
As usual, the documentation generator is written in Crystal itself, with a small (still incomplete) Markdown parser and using ECR (similar to ERB, only processed at compile-time).
One interesting aspect of this documentation generator is that the normal semantic analysis phase of the compiler is applied before it. In this way the documentation generator can have precise type and method information. Not only that, but the semantic phase does macro expansion, so code generated by macros will stil appear in documentation.
Furthermore, you can attach comments to macro invocations:
property macro is expanded the comment attached to that macro call is attached to the
generated nodes. Finally, when you click on “View Source” for the generated method it will take
you to the location of the macro invocation, as the compiler keeps a link between the two.
All of this means that there’s no need to tell the documentation generator that there are special
macros that generate code that needs to be shown in this or that way.
Having the documentation generator as a built-in tool means documentation of libraries will be consistent and people won’t have to worry about which documentation generator to choose. We believe a language is more than just the language itself and that good integrated tools are indispensable for a good, smooth experience.
Now there’s just one thing missing: the documentation itself! We will add it, little by little, and you are very welcome to help us out. Luckily Yukihiro Matsumoto kindly let us use some Ruby documentation as a starting point, given that a lot of APIs are very similar, if not equal. So どうもありがとうございます to him :-)comments powered by Disqus