Em Thu, 10 May 2018 01:38:38 -0700 Christoph Hellwig <hch@xxxxxxxxxxxxx> escreveu: > > * Use either while holding wait_queue_head::lock or when used for wakeups > > - * with an extra smp_mb() like: > > + * with an extra smp_mb() like:: > > Independent of any philosophical discussion not allowing a setence to > end with a single ':' is completely idiotic. Please fix the tooling > instead to allow it, as it is very important for being able to just > write understandable comments. Patches are welcome, although I don't see any easy way to solve it. In English, the common case is that a line with ends with a colon is followed by a list. E. g. foo: - bar1; - bar2. However, in this specific case, it is followed by an ascii artwork. The double colon is a notation that tells Sphinx to not parse the lines at the next block, placing the contents of it inside a literal block. It is used also when the next lines contain a code example, in order to avoid parsing things like @, () and * inside the code block. The kernel-doc tool might eventually have some parsing logic that would replace something to a '::' before sending it to Sphinx. It could, for example, have a "hint" regex that would expect a certain sequence of characters to be at the last line, like: s/ascii\s+artwork.*:/ascii artwork.*::/ or s/code\s+block.*:/code block.*::/ Then, change the kernel-doc comment to use it, like: * with an extra smp_mb() like shown at the following ascii artwork: but IMHO, this is a lot worse than "::": it would be more intrusive and more error-prune. Thanks, 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
