On Tue, Feb 23, 2010 at 8:25 PM, keith <keith_hodges at yahoo.co.uk> wrote:

> Sorry but I didnt understand  much of this. All I really know about
> pragma's is that you can put
>
> <blah: #symbol>
>
> at the top of some code. Where do you put the documentation in this scheme?
>

You can inevnt any selector you want, with multiple arguments.  So you could
choose e.g.

myMethod
    <documentation: 'This method does blah'
      author: 'me'
      apiType: #deprecated>
    self doStuffInADeprecatedWay


Somewhere else, e.g. in your documentation generator you could implement the
#documentation:author:apiType: method, e.g.

documentation: docString author: authorString apiType: typeSymbol
    "Generate doc on outputStream if typeSymbol is a member of the current
doc type set."
   ...


The advantage of this is that the pragma has a specification given by the
implementation of #documentation:author:apiType:.  So unlike the 6 "'s hack,
the link between the metadata and what consumes it is explicit, and senders
and implementors will find producers (methods carrying the pragma) and
consumers (implementors of the pragma).

You then use standard Pragma class-side glue to hook the two up.


You might later add a more or less sophisticated pragma to your generator,
e.g.

DocGenerator methods for documentation pragmas
documentation: docString author: authorString apiType: typeSymbol seeAlso:
aSequenceOfSelectors
    "Generate doc on outputStream if typeSymbol is a member of the current
doc type set."

When a user browses DocGenerator they'll see all the pragmas and be able to
find all uses, be able to add their own etc.


Yes one can use pragmas simply as annotations.  But I think it's much more
powerful when you design pragma selectors that can be implemented, because
a) the consumer of the pragma can be found, not puzzled out, b) it's
extensible in a reasonably obvious manner by adding more selectors to pragma
consumers and c) one can relate multiple consumers (e.g. above a web doc
producer or a e.g. browser that displays api overview along with a class
definition) by using the same selector to consume pragmas in different
generators.


HTH


> Keith
>
>
>
> On Tue, Feb 23, 2010 at 5:57 PM, keith <keith_hodges at yahoo.co.uk> wrote:
>
>> In Sake we have a special Compiler Hack called SakeCompiler.
>>
>> This uses """""" (6 quotes) to mark the end of the method, from then on
>> you can put any content you like in the method.
>>
>> There are accessors docAt: selector
>>
>
> Using a pragma is a better way.  The pragma can include any number of
> strings, and literal strings can^H^H^Hshould be able to contain any
> characters.  One can add additional keywords top define additional metadata.
>  There is already a protocol for accessing pragmas and arguments from
> methods.  One can have multiple pragmas, etc.  If the pragma is
> well-designed one can perform the pragma to output the documentation.  i.e.
> the pragma message is also understood by a formatter/generator, and so by
> browsing implementors of the pragma you get immediately to the code that can
> process said pragma.  There's a wrinkle in that the generator needs to be
> parameterised by the class and selector of the method before it performs the
> pragma, but that aside, it is quite neat.
>
> e.g.
>
> Documentor new
>     outputTo: aStream;
>     documentFrom: aSubClass to: aSuperClass
>
> documentFrom: aSubClass to: aSuperClass
>     (Pragma allNamed: self documentationPragma from: aSubClass to:
> aSuperClass) do:
>         [:p|
>         currentClass := p class.
>         currentSelector := p selector.
>         p message sendTo: self]
>
>
>
>
>> Keith
>>
>>
>
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100224/ed6c5c72/attachment.htm