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