[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Sc-devel] Helper classes



Hi Scott, all,

I think I solved the problem with "pale" colors. It depended on a wrong color scheme inherited from ClassHelpTemplate (which is pale too, indeed).
More, also UGenHelpTemplate has a wrong syntax colorization, if compared to the syntax colorization provided by sclang command.
(this is indeed a dangerous aspect in a help template :) )

I also propose the Helper help file (as usual: raw material). If the Helper classes are committed, I would think that it should be strongly suggested in the documentation style guide to use them instead of templates, which should be shown just as examples. This would enforce consistency, I guess.

(just 2c)

Best

-a-


Attachment: Helper.zip
Description: Zip archive

Helper documentation template autogeneration


Inherits from: Object


Helper allows to autogenerate a documentation template for classes, ugens, topics.

The resulting file strictly follows the provided templates styles, so that you have to worry only about content and not about formatting. 

Note that for consistency you should always use this class while creating help files. 


See also: Documentation Style Guide


Helper structure


Helper class works by inspecting the argument passed to the constructor. It then calls three other  classes specialized for classes, ugens and topics (ClassHelper, UGenHelper, TopicHelper).  TopicHelper is selected if you pass a string (i.e. the topic you want to discuss).

Each of them is given a makeHelp method which generates the help file template. In case of classes, this is done by analysing the source code and retrieving vars, methods, arguments, default values. If you have "private" methods, or other things you think that should not be documented, you have to delete their description from the help file.

Note that not only you do not have to deal with this structure but more typically you simply pass the item to the makeHelp method of Help class (see Examples below).

If closed, the resulting file is deleted. In order to save it, you must "save it as" with a specific name: the item's one is proposed.


Creation / Class Methods


*new (undocumentedObject)

Select the specialized class for documenting the item.

undocumentedObject - the item you want to document. Default value is nil. The method in itself does nothing: you have to send the makeHelp message to the returned instance. 

// of course we can document better this class

h = Helper.new(Helper); // selection

h.makeHelp; // help file creation



Examples


// an undocumented class

h = Helper.new(ClassHelper); 

h.makeHelp ;

// an undocumented topic

h = Helper.new("On the Helper class"); 

h.makeHelp ;

// an undocumented UGen

h = Helper.new(HilbertFIR); 

h.makeHelp ;


// instead of direct instantiantion 

// you may typically use makeHelp  method on the Help class:

// Help.makeHelp wraps the Helper class for you


// The same as before

// an undocumented class

Help.makeHelp(ClassHelper); 

// an undocumented topic

Help.makeHelp("On the Helper class"); 

// an undocumented UGen

Help.makeHelp(HilbertFIR); 




--------------------------------------------------
Andrea Valle
--------------------------------------------------
CIRMA - DAMS
Università degli Studi di Torino
--------------------------------------------------


I did this interview where I just mentioned that I read Foucault. Who doesn't in university, right? I was in this strip club giving this guy a lap dance and all he wanted to do was to discuss Foucault with me. Well, I can stand naked and do my little dance, or I can discuss Foucault, but not at the same time; too much information.
(Annabel Chong)