On Thu, Apr 06, 2023 at 01:04:16PM +0200, Jiri Slaby wrote: > Definitely it _can_ defeat the purpose and be heavily formatted.But it > doesn't have to. It's like programming in perl. > > What I had in mind was e.g. "DOC: TTY Struct Flags": > https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/tty.h#n261 * TTY_THROTTLED * Driver input is throttled. The ldisc should call * :c:member:`tty_driver.unthrottle()` in order to resume reception when * it is ready to process more data (at threshold min). That whole :c:member:'tty_driver.unthrottle()' is an abomination and has no place in a comment. > Resulting in: > https://www.kernel.org/doc/html/latest/driver-api/tty/tty_struct.html#tty-struct-flags > > Both the source and the result are quite readable, IMO. And the markup in > the source is not mandatory, it's only for emphasizing and hyperlinks. > > As I wrote, you can link the comment in the code. But definitely you don't > have to, if you don't want. I like the linking in Documentation as I can put > the pieces from various sources/headers together to one place and build a > bigger picture. > > > I really detest that whole RST thing, and my solution is to explicitly > > not write kerneldoc, that way the doc generation stuff doesn't complain > > and I don't get random drive by patches wrecking the perfectly readable > > comment. > > Sure. Rst _sources_ are not readable, IMO. Only generated man pages or html > are. But code comments are read in a text editor, not a browser. Hence all the markup is counter productive. Why would you go read something in a browser if you have the code right there in a text editor?
