[MacRuby-devel] HotCocoa Part I

[Eloy Duran]

>>>>
>>>
>>> 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