On Fri, May 11, 2012 at 11:30 AM, Christophe Fergeau <cfergeau@redhat.com> wrote:
On Fri, May 11, 2012 at 06:10:24AM +0300, Zeeshan Ali (Khattak) wrote:
The annotations says it all.
You have to know exactly what it means, and it's written very small in the doc, so no, the annotation doesn't say much if you are not familiar with it, and you have to notice it.
The annotation is not supposed to be directly meant for humans, thats why gtk-doc needs to do a better job. i-e the info is already there, just needs translation.
IIRC there was a bug on gtk-doc to generate more helpful output based on these annotations. I don't know if that has been fixed or not but when/if it is, we'll have very silly looking duplication of docs in the same place in the output (there will be duplication of info in source code comment any ways).
I'll fix the doc when this happens.
I discussed this with Stefan like 3 years ago and IIRC he said "its a known issue" and that he has been looking into the matter so can't be sure somebody actually filed a bug about it. But if it hasn't been fixed for all these years, it'll take a competent hacker who is bothered by this to look to get this fixed. -- Regards, Zeeshan Ali (Khattak) FSF member#5124