On 5/3/12 1:23 PM, Jakob Ovrum wrote:
On Thursday, 3 May 2012 at 05:44:47 UTC, Ary Manzana wrote:
On 5/3/12 1:26 AM, Jakob Ovrum wrote:
This project is finally published and documented, so here's an
announcement.
https://github.com/JakobOvrum/bootDoc
bootDoc is a configurable DDoc theme, with advanced JavaScript features
like a package tree and module tree, as well as fully qualified symbol
anchors. The style itself and some of the components come from Twitter's
Bootstrap framework.
Demonstration of Phobos documentation using bootDoc
http://jakobovrum.github.com/bootdoc-phobos/
Very nice!
But why the symbols inside std.algorithm, for instance, are not sorted?
http://jakobovrum.github.com/bootdoc-phobos/std.algorithm.html
(they are kind of sorted by chunks...)
The symbols in the symbol tree appear in the order the symbols appear in
the documentation, which is the order of declaration in the original
source (DMD does it this way). I think it would be a little confusing if
the symbol tree was alphabetically sorted, while the main documentation
was in order of declaration.
It is possible to rearrange everything with JavaScript of course, but...
I think this might be going a little bit too far.
What do you think?
I don't think the main documentation order is right in the first place.
If a module provides many functions, like std.algorithm, I don't see how
there could possibly be an "intended" order, like "these are more likely
to be used".
In any case, if I want to quickly find a function, for example "remove"
or "insert" or something I think might have the name I'm looking for,
alphabetical order is the best way to go.
Now if it only had cross references... :-P
If I understand you correctly, any kind of automatic cross-referencing
would need post-processing of DMD's generated output. I am considering
such post-processing, but it would massively change the project (a lot
less would require JavaScript), and completely bind the project to the
included generator tool.
I think the tool needs more trial-by-fire testing to determine whether
it's good enough to be mandatory.
Oh, I just said that because I have a pull request waiting for that
feature to be incorporated in DMD... but I don't think it'll happen...
