[sldev] framework documentation pattern

[Lawson English]

Lawson English wrote:
>
> On a related note, I'm learning much about the existing classes as I 
> try to figure out how to do what I want. What is the proper format for 
> documenting the classes and how they are  used?
>

I'm putting this issue in its own thread.

I couldn't find anything on the wiki about how the framework should be 
documented, so I'm proposing something along the lines of Apple's Cocoa 
framework documentation, though probably nothing quite as elaborate:

http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/Classes/NSOutlineView_Class/index.html#//apple_ref/doc/uid/TP40004079


As an aside, there are huge amounts of work that can/should be done to 
make these frameworks more usable, up to and including an entire 
rewrite. Several classes stand out as being kitchen sink classes and 
should definitely be rewritten such as llInventoryPanel and the viewer 
class itself. A REAL rewrite will need to await rewriting of the lower 
level classes, though at least some work can be done using the existing 
classes (I hope).

The LLSD class seems to be designed to allow better communication 
between framework objects, among other uses, so any redesigned classes 
should probably use LLSD when talking to each other. This last is only 
the vaguest of intuitions on my part, so feel free to gently correct me 
if I'm wrong about its intended use or the utility of using it when 
rewriting the framework.