> 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."

I use this approach in System-Exports - It has taken me 4 years to  
find a use for pragmas!

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

Ah, but since the pragma knows which method it is defined in it can  
get its documentation from the first code comment, or by invoking the  
method. In System-Exports I do something like this...

"this is the documentation here"

<package: 'System-Exports' version: '1.0'>

  Then package:version: calls

self  thePragmaClass firstCommentAt: self thePragmaSelector.

Or with the """""" scheme.

self  thePragmaClass docAt: self thePragmaSelector.

Using this scheme, every method can be the equivalent of a class  
comment, AND you can use pragmas to tag, collates and index your  
documentation.

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

This is also how System-Exports works.

#> Export slices explore.

finds all pragmas that AnnotatedExportSlice understands.
>
>
> 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,


Agreed

> 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

I have two types of pragma, the first which picks the processing  
class, e.g. <package: 'MyPackage version: '1.0'> and the rest are just  
fed into a keyword/value dictionary. <project: 'MyProject' author:  
'kph' item: 7> becomes #project: -> 'MyProject, #author: -> 'kph'  
#item -> 7.

Is it just me or is searching for pragmas in the whole system  
painfully slow?

Is there any good reason not to do, Pragma allInstancesDo: ?

> (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.

thanks for the detailed explanation

Keith
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20100224/3c670235/attachment.htm