On Mon, 7 Sep 2015 17:01:59 -0300 Danilo Cesar Lemes de Paula danilo.cesar@collabora.co.uk wrote:
The "highlight" code is very sensible to the order of the hash keys, but the order of the keys cannot be predicted. It generates faulty DocBook entries like:
- @<function>device_for_each_child</function>
Sorting the result is not enough some times (as it's deterministic but we can't control it). We should use an array for that job, so we can guarantee that the order of the regex execution on dohighlight is correct.
OK, I've spent a bunch of time with this, comparing the results before and after. The output you mention is clearly wrong, but there might be room to differ over what the root cause is.
That output is caused by @device_for_each_child() in the comments. This happens for a few other functions as well, and I think it's wrong. @ is used to indicate parameters (or structure fields); I'm not sure why people are using it for functions that are *not* one of the above. Formatting the function names as a parameter doesn't seem right either.
There is the occasional case where the parameter *is* a function and the text uses the () notation (threadfn(), for example). Having the "parameter" style win out over the "function" style in such cases is OK, I guess, but it would be good to format the parentheses along with the name. The function patterns there now drop the parentheses entirely, which seems a bit strange to me.
I guess I'll apply the patch; determinism is good, and it doesn't make anything screwy that wasn't already that way. But I think we should fix the misapplied @s and sort out function formatting in general. One of these days...
Thanks,
jon