I think that fundamentally you should not use pragmas for documentation. I guess that people use it to be able to provide minimal structure for their documentation. A better solution would be to have a simple convention for this kind of structure that is easy to parse, e.g using newlines to separate the ‘keywords’ and their ‘values’ and just have a comment. For example:
Now: <api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged:> Comment convention: “ api: #block getter: #acceptBlock registration: #whenAcceptBlockChanged: " Easy to parse, and easy to write conversion logic for batch transformation of these comments. > On Feb 26, 2015, at 13:12, Ben Coman <[email protected]> wrote: > > Could you provide a sample, so this anti-pattern is more clear. > cheers -ben > > On Fri, Feb 27, 2015 at 12:08 AM, stepharo <[email protected] > <mailto:[email protected]>> wrote: > We are cleaning spec and the fact that method selectors are used everywhere > in pragmas as meta description makes the navigation terrible. > I'm removing them to be able to understand who is really calling the methods. > So there is probably a lesson there. > > Stef > > > ---> Save our in-boxes! http://emailcharter.org <--- Johan Fabry - http://pleiad.cl/~jfabry PLEIAD lab - Computer Science Department (DCC) - University of Chile
