On Wed, 9 May 2018 17:20:26 +0200 Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote: > The whole rst wankery is detrimental to that interface in order to > pander to something else.. I don't see the value. I've objected before, > and I suppose I'll object again. One person's wankery is another's integrated, browsable, and searchable documentation that shows some signs of having actually been thought about, I guess. > > It's a simple colon. It goes along with the /** marker for kerneldoc > > comments and the @ markers found within them, both of which you seem to > > have found a way to live with. > > Barely, and personally I tend to not bother with kerneldoc much. Most of > the comments I write lack the extra *, and I note that the other fix to > this problem it to drop that spurious * here as well. Perhaps you'd like to post a patch removing the kerneldoc mechanism? It would make my life a lot easier...:) > The @arg thing is okay, it clearly distinguishes arguments/variable > names from regular text. But "::" is the C++ class member syntax, not > the start of an English enumeration or the like. Not sure what C++ has to do with anything, unless we want to bring in $LANGUAGE_WE_DISRESPECT spuriously. I'm sure it's the Perl do-five-different-things-magically syntax too. It's probably an entire natural-language processing system in Haskell. It also happens to be the Sphinx "start literal block" syntax. > > You're not the only consumer of the docs. You may not appreciate the > > improvements that have come, but others certainly do. I do hope that you > > can find it in youself to avoid vandalizing things for everybody else ...? > > Why should I care for people not using text editors to write code? The set of "people using text editors to write code" is a superset of the set containing only Peter Zijlstra. Many of the people who have used text editors to write the very code we all work on find a minimally structured documentation system to be useful. Out of respect for them, if nothing else, I'll ask again, please, that you suffer the substantial cognitive drain of skipping over an extra colon. Thanks, jon -- 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
