Hi Laurent,
Sure, I'm in no hurry at all to start work at this.
Just saying that my preference would be this path.
Which was actually meant more to keep the people on this list in the
loop on stuff
we discuss elsewhere than for you :-)
- Eloy
PS: Could you point me to exactly which db's you mean?
On Dec 3, 2008, at 10:42 AM, Laurent Sansonetti wrote:
On Dec 3, 2008, at 12:56 AM, Eloy Duran wrote:
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.
I think he's talking about the Xcode docsets which embed a SQLite
database. But last time I looked the DB included HTML snippets, so
yes HTML parsing would still be required.
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…
Yes, parsing the Apple HTML is not a good idea, maintenance wise :-)
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.
The HTML is generated from a human-readable description (XML I
think, which therefore may not classify as human-readable, but well)
which I could perhaps have access to it and generate some Ruby-
readable (RI?) data out of it. But I cannot promise anything at this
point, I first need to finish all the items on my TODO list before
starting to investigate this path :-)
Laurent
_______________________________________________
MacRuby-devel mailing list
MacRuby-devel@lists.macosforge.org
http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel
_______________________________________________
MacRuby-devel mailing list
MacRuby-devel@lists.macosforge.org
http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel
