OK; here's a partly-baked idea, loosely inspired by Python
docstrings.
<PBI>
The HC declarations are (I assume) stashing information away in some
sort of data structure. If not, they certainly could be (:-). Once
the information is available at runtime, any HC script could
retrieve
them for use in online documentation.
Of course, as RK indicates, HC is lazy about loading frameworks.
So,
a comprehensive documentation generator would have to force
loading of
all possible frameworks.
It may also be that HC doesn't store as much information as we'd
like
to have in the docs. No problem; add a few more methods (etc) to
let
developers add these "annotations".
</PBI>
The mapping files do create data structures, I was totally going to
get these to produce documentation on what was mapped, what the
defaults were, what custom methods exist, etc. Its pretty easy to
do I think. The issue I ran into was I want the rest of the
documentation for the class. All the indexes for the API docs are
in SQLite DBs (although not documented). If we could extract that
and make an integrative documentation browser it would help a lot
for folks trying to figure out what to do.
If you mean docutil, I think it will be of very little use…
It only (afaik) returns a link to where the documentation lives,
you will still need to parse it out of the actual HTML docs.
Which is doable, I wrote something which does that for RubyCocoa before,
however it's not a pleasant thing to do. Because Apple creates very
bad HTML
for parsing purposes and they have this annoying habit ;-)
of updating it every other week or so…
So like I discussed with Laurent, I am open to tackling this by
rewriting it to a tool
which uses XML (or some other more parseable format) _IF_ Apple would
provide it.
Apple currently does not provide anything like that to the outside
world.
Another option, also discussed with Laurent, would be to write it
based on a sample (like a regression test)
and that Apple may run it internally, if they prefer.
So unless Apple would provide this, I wouldn't start on this venture
again or encourage anyone else to do so.
Cheers,
Eloy
_______________________________________________
MacRuby-devel mailing list
MacRuby-devel@lists.macosforge.org
http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel
