Crystal 0.5.6 has been released!
The most important feature of this release is the incluson of a prelimiary doc command
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:
- Documentation must be written using Markdown, which is pretty popular and easy to read and write.
- You have a class tree at the left
- Superclass, included modules and knwon subclasses are shown
- References to types are automatically linked
- References to types mentioned in type restrictions are linked
- References to methods must be written like
#methodorType#method - A "View Source" link is provided for every method, that takes you to the line of code where the method is defined (only for code that is hosted on GitHub for now)
- Code sections are highlighted, so examples showing usage of a class or method can be easily embedded and will be nicely formatted.
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:
class Foo
# The comment for some_property
property some_property
end
Once the 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 :-)