<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div><blockquote type="cite"><div class="gmail_quote">On Tue, Feb 23, 2010 at 8:25 PM, keith <span dir="ltr"><<a href="mailto:keith_hodges@yahoo.co.uk">keith_hodges@yahoo.co.uk</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> <div style="word-wrap:break-word">Sorry but I didnt understand much of this. All I really know about pragma's is that you can put<div><br></div><div><blah: #symbol></div><div><br></div><div>at the top of some code. Where do you put the documentation in this scheme?</div> </div></blockquote><div><br></div><div>You can inevnt any selector you want, with multiple arguments. So you could choose e.g.</div><div><br></div><div>myMethod</div><div> <documentation: 'This method does blah'</div> <div> author: 'me'</div><div> apiType: #deprecated></div><div> self doStuffInADeprecatedWay</div><div><br></div><div><br></div><div>Somewhere else, e.g. in your documentation generator you could implement the #documentation:author:apiType: method, e.g.</div> <div><br></div><div>documentation: docString author: authorString apiType: typeSymbol</div><div> "Generate doc on outputStream if typeSymbol is a member of the current doc type set."</div></div></blockquote><div><br></div><div>I use this approach in System-Exports - It has taken me 4 years to find a use for pragmas!</div><div><br></div><blockquote type="cite"><div class="gmail_quote"><div>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).</div></div></blockquote><div><br></div><div>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...</div><div><br></div><div>"this is the documentation here"</div><div><br></div><div><package: 'System-Exports' version: '1.0'></div><div><br></div><div> Then package:version: calls</div><div><br></div><div>self thePragmaClass firstCommentAt: self thePragmaSelector.</div><div><br></div><div>Or with the """""" scheme.</div><div><br></div><div><div>self thePragmaClass docAt: self thePragmaSelector.</div><div><br></div><div>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.</div><div><br></div></div><blockquote type="cite"><div class="gmail_quote"><div><div>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.</div></div></div></blockquote><div><br></div>This is also how System-Exports works.</div><div><br></div><div>#> Export slices explore.</div><div><br></div><div>finds all pragmas that AnnotatedExportSlice understands.<blockquote type="cite"><div class="gmail_quote"><div><br></div><div>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, </div></div></blockquote><br></div><div><br></div><div>Agreed</div><div><br></div><div><blockquote type="cite"><div class="gmail_quote"><div>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 </div></div></blockquote><div><br></div><div>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.</div><div><br></div><div>Is it just me or is searching for pragmas in the whole system painfully slow?</div><div><br></div><div>Is there any good reason not to do, Pragma allInstancesDo: ?</div><div> </div><blockquote type="cite"><div class="gmail_quote"><div>(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.</div> </div></blockquote></div><br><div>thanks for the detailed explanation</div><div><br></div><div>Keith</div></body></html>