Ben Coman wrote
On Fri, Jun 24, 2016 at 10:55 PM, Clément Bera <
bera.clement@
> wrote:
Hi.
Pragmas are selectors hence they're browsable. You can implement a method somewhere with the pragma selector name that includes the documentation. In VW they were careful about that and most, if not all, of their pragmas are carefully commented this way.
Should this be concentrated in a class like PragmaDocumentation, or spread out (I don't know how).
Since pragmas are an open set and can be added by any package, concentrating them in one place doesn't sound like a good idea. The best place to have the comments is with the code. If the pragmas name real selectors, comment the implementation. If the pragmas are merely tags, comment the method that declares them as pragmas (e.g. VisualWorks requires you to declare the symbols as pragmas before using them). Examples: SUnit.TestCase class>>#testMethodTags declares a couple of pragma selectors for instance methods. testMethodTags "Any method tagged with a <test> pragma is considered a test selector candidate" "<uses:> tags are used to compute instance specific resources for the tagged test. The argument is a symbol for the class name, or a binding reference to the same." <pragmas: #instance> ^#(#test #uses:) SUnit.TestCase class>>#testResourceTags declares a class method pragma for resources. testResourceTags "<resource:> tags are used to compute instance specific resources for the tagged test. The argument is a symbol for the class name, or a binding reference to the same." <pragmas: #class> ^#(#resource) ApplicationModel class>>menuMethodPragmas declares a whole slew of selectors for menus. But it neglects to provide comments in it or in the list of selectors in the Menu class. menuMethodPragmas <pragmas: #instance> <pragmas: #class> ^Menu pragmas However, VW does comment the actual methods: computedSubmenu: label nameKey: key menu: menuIDs position: position "This pragma expects the body of the method marked with it to answer a Menu that will be used as a submenu with the label and position specified by the pragma."
cheers -ben
For example, if you have the pragma <foo> and you implement the method MyClass class >> #foo with some comments in it and you can double click on the pragma <foo> to select its content (foo) and press Cmd+M (or right click implementors) to get to the method having the documentation.
On Fri, Jun 24, 2016 at 3:54 PM, Alexandre Bergel <
alexandre.bergel@
> > wrote:
Hi!
A pragma may be very obscure. For example, I do: Pragma allInstances anyOne =>
<debuggerCompleteToSender>
If I want to know more about this
<debuggerCompleteToSender> is actually
quite challenging. I see many methods having that pragma, but not idea what it is for. I see that Halt>>signalerContext and Process>>complete: that use that pragma somehow. But still, I have no idea when I should use that pragma in my method.
What about having a way to comment pragma? Maybe something like -=-=-=-=-=-= Object subclass: #Pragma instanceVariableNames: 'method keyword arguments *comment*' -=-=-=-=-=-=
And a simple way to annotate pragmas? Just an idea.
Cheers, Alexandre -- _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: Alexandre Bergel http://www.bergel.eu ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
-- View this message in context: http://forum.world.st/Having-comments-for-pragma-tp4902987p4903138.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.