<br><br><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> ...</div><div>
<br></div><div><br></div><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><br></div><div>You then use standard Pragma class-side glue to hook the two up.</div><div><br></div><div><br></div><div>You might later add a more or less sophisticated pragma to your generator, e.g.</div><div><br></div>
<div>DocGenerator methods for documentation pragmas</div><div><div>documentation: docString author: authorString apiType: typeSymbol seeAlso: aSequenceOfSelectors</div><div> "Generate doc on outputStream if typeSymbol is a member of the current doc type set."</div>
<div><br></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><br></div></div><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, 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.</div>
<div><br></div><div><br></div><div>HTH</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div style="word-wrap:break-word"><div><br></div><div><font color="#888888">Keith</font><div>
<div></div><div class="h5"><br><div><br></div><div><br><blockquote type="cite"><div class="gmail_quote">On Tue, Feb 23, 2010 at 5:57 PM, keith <span dir="ltr"><<a href="mailto:keith_hodges@yahoo.co.uk" target="_blank">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"> In Sake we have a special Compiler Hack called SakeCompiler.<br> <br> This uses """""" (6 quotes) to mark the end of the method, from then on you can put any content you like in the method.<br>
<br> There are accessors docAt: selector<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>e.g.</div><div><br></div><div> Documentor new</div><div> outputTo: aStream;</div><div> documentFrom: aSubClass to: aSuperClass</div><div><br></div><div>documentFrom: aSubClass to: aSuperClass</div>
<div> (Pragma allNamed: self documentationPragma from: aSubClass to: aSuperClass) do:</div><div> [:p|</div><div> currentClass := p class.</div><div> currentSelector := p selector.</div><div> p message sendTo: self]</div>
<div><br></div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><font color="#888888"> <br> Keith<br> <br> </font></blockquote></div><br>
<br></blockquote></div><br></div></div></div></div><br><br>
<br></blockquote></div><br>