Em Thu, 10 May 2018 13:42:58 -0300 Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> escreveu: > Em Thu, 10 May 2018 09:38:46 -0600 > Jonathan Corbet <corbet@xxxxxxx> escreveu: > > > On Thu, 10 May 2018 11:21:13 -0300 > > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: > > > > > The problem with a hint-based mechanism is that it will generate > > > false hints. If added, we may end by needing to add extra tags to > > > disable the hints mechanism where it gets wrong, or to periodically > > > do code changes at kernel-doc comments in order to make the hints > > > logic happy. > > > > > > So, IMO, we should provide non-hints based mechanism, like forcing the > > > string that prepends the colon to have a keyword that will make it to > > > parse the block as literal, where expressions like: > > > > > > See the code-block foo: > > > See the following code example: > > > See the following flow diagram: > > > See the following artwork: > > > > > > Is the best alternative to avoid "::", as on the enclosed patch. > > > > But this, too, is a hint-based mechanism. Thanks for the patches, I'll > > keep them around, but I would like an opportunity to try to do better > > before applying them. I fear that using magic words in this way will > > lead to a constant stream of surprises, and I'd like to avoid that if > > possible... > > Yes, it is still hint-based. A careful selection of the "magic spell > words/phrases" would minimize the risks of false positives, but it > could still lead into some unwanted surprises. Btw, running this: $ git grep -A2 "\*\s.*following.*(code|example|artwork|flow|diagram).*:$" currently doesn't have a single match. If we force a two word combination, and an ending with ":" should be enough to not having too much false positives. Regards, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
