[MacRuby-devel] HotCocoa Part I

[Laurent Sansonetti]

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