[MacRuby-devel] HotCocoa Part I

[Richard Kilmer]

On Dec 2, 2008, at 9:00 PM, Chris McGrath wrote:

>
> On 3 Dec 2008, at 00:45, Rich Morin wrote:
>
>> At 01:27 +0000 12/3/08, Chris McGrath wrote:
>>> One thing I've been considering since watching your RubyConf
>>> presentation via confreaks is ...
>>
>> Just to be clear, Rich Kilmer is the HC developer that made the
>> RubyConf presentation; I'm just a MacRuby and HotCocoa wannabe...
>>
>
> Ooops, I must have some sort of richlexia, you aren't the first two  
> I've got confused!

Sorry guys, just catching up with this thread...


>
>>
>>> ... auto-generating documentation about what's mapped to what.
>>> I haven't looked at the code enough to know if it's feasible,
>>> but I'd like to see something like:
>>>
>>> text_field -> NSTextField (selectable: false, bordered: false, ...)
>>> #i.e. the defaults
>>>
>>> Most of these would be obvious, but are currently "hidden" away down
>>> in the MacRuby source. I'd like to see mappings both ways, so as
>>> someone who knows a bit of cocoa I can easily go check if NSFoo has
>>> been wrapped by someone and what the wrappings are. I love how the
>>> mappings are implemented, but I won't be able to keep them all in my
>>> head!
>>
>> 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.

>>
>>
>
> On first skim, it seems that as well as adding ruby methods and  
> constants, lib/hotcocoa/mapping.rb could be persuaded to do  
> something like that. I'd envisage this being a tool you could run on  
> a mapping file to spit out html / rdoc / whatever. I don't have time  
> this week but I'd like to look into something like this soon.
>
> Cheers,
>
> Chris
> _______________________________________________
> MacRuby-devel mailing list
> MacRuby-devel at lists.macosforge.org
> http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel