13:46 <dieterv> ensonic: are you Stefan Sauer from https://bugzilla.gnome.org/show_bug.cgi?id=676133 ?
14:02 <ensonic> dieterv, yes
14:02 <dieterv> ensonic: ok, about those extra Tags: g-i has defined, I'll have to ask jdahlin or walters
14:03 <dieterv> ensonic: don't know the history behind them, or how widespread their usage may be
14:03 <dieterv> ensonic: but I have another question regarding gtk-doc comment blocks:
14:03 <dieterv> ensonic: would you say the following is a correct description: http://fpaste.org/9rgP/ ?
14:04 <ensonic> dieterv, gtk-doc has a user-manaul that describes the format, are you aware of it?
14:05 <dieterv> ensonic: yes, and I used that together with gtkdoc-mkdb.in's sources to construct it
14:05 <ensonic> dieterv, in the gtk-doc sources it is unser help/manual and you can show it with yelp
14:05 <dieterv> ensonic: ...when I rewrote gobject-introspection's annotationparser
14:07 <ensonic> dieterv, your format description looka good, a few comments
14:07 <ensonic> dieterv, parameter descriptions and tag_description can be multiline
14:07 <ensonic> oh right, you said that
14:08 <dieterv> ensonic: yes, there can be 0 or more parameters, each optionally having a description
14:08 <dieterv> ensonic: same for tags
14:08 <dieterv> the only difference between parameter and tag descriptions that I'm aware of is that parameter descriptions cannot span multiple paragrahs
14:08 <ensonic> sounds about right, now someone create a tool to produce all corner cases from that spec and test gtk-doc on it :)
14:09 <dieterv> ensonic: because the empty line would trigger the start of the comment_block_description
14:09 <ensonic> dieterv, yep
14:09 <dieterv> ensonic: working on that, in g-i
14:09 <ensonic> the format is quite ad-hoc unfortunately, it grew very organically :/
14:09 <dieterv> there's about 120 tests for the re's, testing complete blocks in underway
14:09 <dieterv> yeah, I understood as much
14:10 <dieterv> ensonic: now, the ultimate question:
14:11 <dieterv> ensonic: the comment_block_description *has* to be located before any Tag: is written
14:11 <dieterv> ensonic: because there is no other way to make the distinction between a multi paragraph Tag: description and what could be a comment_block_description
14:11 <dieterv> ensonic: correct?
14:12 <ensonic> dieterv, one part that needs updating in gtk-doc is the one that handles the block parsing state (scanSourcefile). this hardcodes the possible sections
14:12 <ensonic> yes, thats right
14:13 <dieterv> ok, so that then closes the g-i clone of bug 676133 (674658) :)
14:13 <dieterv> ensonic: also, what do you mean by sections?
14:13 <ensonic> in one of my upcomming lives I want to rewite the ScanSourcefile to atleast ignore unknown tag-sections
14:14 <dieterv> ah, am preparing a patch to make g-i do exactly that
14:14 <dieterv> as it is currently using a list of [gtk-doc tags] + [g-i tags]
14:14 <ensonic> dieterv, right now scansourcefile tracks state using in_return, in_since, in_deprecated, ... - it can't cope with unknown tags (and therefor it would merge them to the main docs where they will appear verbatim)
14:15 <dieterv> ensonic: indeed, that is exactly what 676133 is about
14:15 <dieterv> ensonic: so, this is the re I'm currently playing with: http://fpaste.org/Wysp/
14:15 <ensonic> dieterv, still for that the tags have to be below the main-comment
14:16 <dieterv> ensonic: the idea being that tag_name is later matched to said list of known tags (instead of hardcoding in the re)
14:16 <dieterv> ensonic: if it is a known tag, good proceed
14:16 <dieterv> ensonic: if not, emit a warning
14:17 <ensonic> ohh, my brain, I am currently working on something complicated, no capacity left to verify the regexp :/
14:18 <dieterv> ensonic: was just fyi, we have a test suite to verify it functions correctly ;)
14:18 <dieterv> ensonic: so, we agree that tags having to be below the comment_block_description is something set in stone by the format
14:20 <ensonic> dieterv, pretty much, yes
14:20 <dieterv> ensonic: and we also agree that gtk-doc at some point will have to find a way to ignore unkown (from the point of view of gtkdoc-mkdb::ScanSourceFile) tags ?
14:22 <ensonic> dieterv, unfortunately we don't agree on that one, I want to rewrite the scanner to eventually do it, or atleast have a list of tags to hide, but imho gi should never ever started to introduce these form of tags
14:22 <ensonic> dieterv, just imagine someone writes "Note: this api is experimental" we don't want to all of a sudden hide it
14:23 <ensonic> the doc comments have not much structure and thus you need to be careful when introducing new syntax
14:23 <dieterv> ensonic: "Note&colon; this api is experimental" ?
14:23 <ensonic> I did quite some grepping of sources to check wheter code uses "parameter: (something): something" before that was added to the syntax
14:24 <dieterv> ensonic: takes away the ambiguity whether not is a tag is current or future gtk-doc
14:24 <ensonic> dieterv, sure, but we don't want to break existing docs, right
14:24 <dieterv> ensonic: ie, the documentation writer states without a doubt that Note&colon; is description
14:24 <dieterv> ah, off course...
14:25 <ensonic> dieterv, also it is ugly to write that in the source files unfortunately
14:26 <ensonic> if possible I would ask for "Annotations: (type int) (transfer full):" instead of "Type: int", "Transfer: full"
14:26 <dieterv> ensonic: agreed, although these days people are getting pretty used to entities, with XML and HTML being everywhere
14:26 <dieterv> jdahlin: ping re "14:26 <ensonic> if possible I would ask for "Annotations: (type int) (transfer full):" instead of "Type: int", "Transfer: full""
14:26 <ensonic> that makes the parsing simpler and introduces less keywords
14:27 <dieterv> ensonic: s/keywords/tags/ ?
14:27 <ensonic> dieterv, yes
14:27 <dieterv> (just to be sure we're still talking about the same thing)
14:27 <ensonic> dieterv,  "Annotations:" is negotiatable :)
14:28 <dieterv> ensonic: about those extra tags, like I said, we'll need the input of jdahlin and/or walters
14:28 <ensonic> if we can agree on a new tag for symbol wide annotations, I'll make the related changes in gtk-doc, but I would still prefer to just add them to the identifier line (first line)
14:28 <dieterv> ensonic: as I don't know the history behind them, or how widespread their usage may be
14:29 <ensonic> dieterv, sure, I know - I'll be around for 3 more hours
14:29 <dieterv> ensonic: if I'm correct, the only annotation accepted on the identifier line is (skip) atm
14:29 <ensonic> dieterv, they are not around for long and everyone who started using them will have trouble with the docs anyway
14:29 <dieterv> well, we pinged jdahlin and walters is not yet online so let's wait and see a bit
14:30 <ensonic> dieterv, if you come to a resolution while I am offline, please update the bug or mail to gtkdoc list
14:30 <dieterv> ensonic: will do
14:30 <dieterv> ensonic: thanks for you input :)
14:30 <ensonic> yw, thanks for caring
14:31 <dieterv> halfline: ping

< a bit later />

15:42 <dieterv> walters: talked a bit with ensonic earlier about https://bugzilla.gnome.org/show_bug.cgi?id=676133 and https://bugzilla.gnome.org/show_bug.cgi?id=674658
15:42 <dieterv> walters: http://fpaste.org/Pta0/
15:43 <dieterv> walters: could you enlighten us what's going on with those g-i specific "Tags:" ?
15:44 <walters> dieterv, i do agree with 14:26 <ensonic> if possible I would ask for "Annotations: (type int) (transfer full):" instead of "Type: int", "Transfer: full"
15:45 <walters> dieterv, i don't recall why we also had the option to specify them at the block level; it might have simply been an accident of the old parser
15:46 <walters> well let me comment on the bug
15:48 <dieterv> walters: thanks :)
15:52 <dieterv> walters: note that we have more tags than just Type: and Transfer:
15:52 <dieterv> walters: the complete list is: Virtual, Attributes, Rename to, Type, Unref func, Ref func, Set value func, Get value func, Transfer, Value
15:55 <ensonic> walters, if  "Annotations:" sould like a good tag, please let me know on the bug and purge the mentioning of the block level tags from the wiki, I'll make gtk-doc grok it then
15:57 <dieterv> walters: in the comment you just added, you've annotated the identifier of the comment block
15:58 <dieterv> walters: and didn't use an Annotation: tag
15:58 <dieterv> walters: do we go in that direction then and add some sort of deprecation warning to annotationparser.py for the list of tags I mentioned above?
16:00 • dieterv has to go catch his trans
16:00 <walters> dieterv, though i'm not sure why we need Annotations: given that we have header annotations
16:00 <dieterv> s/trans/train/ even...
16:00 <ensonic> walters, I agree, no extra tag would be the best
16:00 <dieterv> walters: if annotating the identifier already works, we don't need an Annotations: tag at all :)
16:00 • dieterv runs
