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.
