Following up on file-position locking

Posted Aug 13, 2023 3:58 UTC (Sun) by tialaramex (subscriber, #21167)
In reply to: Following up on file-position locking by willy
Parent article: Following up on file-position locking

I didn't realise Rust people considered ReST (and Asciidoc and several other alternatives). I think you may wait a long time if you're expecting the choice to change but maybe I'll be proved wrong.

That current kernel-doc style is a huge turn-off. Saying the obvious is exactly the kind of thing which makes developers hate writing docs but also makes users hate reading them. There is no overlap between the set of people who need a document explaining that the parameter named "page" is the page, and the set of people who read kernel docs.

Presumably kernel-doc pre-dates the choice of ReST ?

to post comments

Following up on file-position locking

Posted Aug 13, 2023 4:32 UTC (Sun) by mathstuf (subscriber, #69389) [Link]

I'll say that, at least for myself, Markdown is far easier to write and read. Remembering what extensions work where sucks, but the core is solid. ReST does make better *rendered* docs because it has a bit more control for custom things like cross-linking and such without relying on a sufficiently sophisticated renderer, but I find it to be a bit heavy in the syntax department for my tastes (especially having to match section titles with the appropriate symbol of the right length too). It's not like either make it easy to properly typeset things like LaTeX2ε anyways (IIRC, it was impossible to get the subscript italics as part of a single word without extensions).

Following up on file-position locking

Posted Aug 13, 2023 8:43 UTC (Sun) by Sesse (subscriber, #53779) [Link]

Without having ever used kernel-doc, so just commenting generally: The biggest problem with writing the obvious is that it takes the place of real documentation. If you put in a big blurb saying nothing useful, it still looks optically like you documented it, and so you don't worry about it from there.

(That big blurb saying nothing useful can also be the BSD or GPL header :-) )