On Fri, Feb 27, 2015 at 12:53 AM, Johan Fabry <[email protected]> wrote:
> > 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. > And MOST importantly, easy to identify that it doesn't affect program execution! cheers -ben > > 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]> 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 >> >> >> > > >
