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 <btc@openInWorld.com> 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 <stepharo@free.fr> 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