On Tue, Jun 03, 2025 at 08:01:02AM -0600, Jonathan Corbet wrote: > Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> writes: > > >> Re: the c:func: stuff - > >> > >> Well, the right thing is making function + type names clearly discernable, and > >> it just putting in the function name like that absolutely does not do the right > >> thing in that respect. > >> > >> I feel strongly on this, as I've tried it both ways and it's a _really_ big > >> difference in how readable the document is. > >> > >> I spent a lot of time trying to make it as readable as possible (given the > >> complexity) so would really rather not do anything that would hurt that. > >> > > > > Somebody told me that in _other_ .rst's, seemingly, it does figure out xxx() -> > > function and highlights it like this. > > > > But for me, it does not... :) > > OK ... If you look at what's going on, some of the functions will be > marked, others not. The difference is that there is no markup for > functions where a cross-reference cannot be made (because they are > undocumented). > > We could easily change the automarkup code to always do the markup; the > problem with that (which is also a problem with the existing markup > under Documentation/mm) is you'll have rendered text that looks like a > cross-reference link, but which is not. We also lose a clue as to which > functions are still in need of documentation. Isn't it a pretty egregious requirement to require documentation of every referenced function? I mean if that were a known requirement I'd simply not have written this document at all, frankly. And it's one I feel is really quite important, since this behaviour is complicated, confusing and has led to bugs, including security flaws. I really think we have to be careful about having barriers in the way of people writing documentation as much as possible. > > The right answer might be to mark them up differently, I guess. But... what I'm doing here, and what mm does elsewhere works perfectly fine? Why do we need something new? Surely this cross-referencing stuff is more useful for API documentation that explicitly intends to describe functions like this? > > jon
