Let me reply in one place as we're currently having 2 largely similar conversations in parallel which is unhelpful... :) On Tue, Jun 03, 2025 at 08:37:23AM -0600, Jonathan Corbet wrote: > Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> writes: > > > But to repeat - 'given C's weirdness with typing I really prefer to be > > explicit in referencing a struct vs. e.g. a typedef.' > > ...and I think that makes perfect sense. > > >> Why would you *not* want to cross-reference something and make life easier > >> for your reader? > > > > Because it apparently requires me to document every function I reference? > > Unless I'm missing something? > > > > I may be misunderstanding you. > > > > If not then fine, I can delay this patch, go off and do a 'cleanup' patch > > first, that will drop the '!'s and come back to this. > > > > But if I need to document every referenced function that just isn't > > feasible for me with my current workload. > > > > Please clarify! > > Hopefully I already have - I'm in no position to enforce such a > requirement, even if I thought it would be a good thing -- and I don't. I think Andrew would think otherwise :) Everybody respects you a great deal, myself included, so your opinion counts for a LOT. > It's hard enough to get documentation written as it is, I certainly > don't want to make it harder. Yeah, I mean I take your points and it's important to me to make sure I've done this as well as I can, but this is my main concern here. Often times this stuff feels rather thankless... so we must maintain a balance here I feel. Anyway, I think we can figure out a good solution here that should hopefully be satisfactory for all (see below...) > > My suggestion would be: proceed with your changes for now, it was never > my purpose to put obstacles there. I'll look at having automarkup do > something a bit more useful for references that lack documentation, then > maybe I'll do a cleanup pass on some of the mm docs if nobody else gets > there first. > > Thanks, > > jon Thanks, I appreciate that. So I want to address your concerns as well as I can. I think I have misunderstood you a little bit here too (text is a poor medium, yada yada) so let me try to nail down what I feel is the sensible way forward: 1. Once I am confident I have correctly addressed Jann's feedback I'll respin a v2 with the various 'sins' in place for the time being. 2. I will also drop the 'since v6.14' stuff you rightly raised in this respin. 3. I will create a follow-up series to address these issues in this file -in general-: - Drop '!' from every reference so we get automated cross-referencing - I think now I understand the point (hopefully!) that Sphinx with automagically link every unique reference to a function/struct/etc. to one another. - Perhaps hack in a **struct ** prefix so we get the 'best of both worlds' on this for types...? I think my misapprehension about defining functions was not realising that by doing :c:func:etc without the ! would automatically provide that definition upon first reference to that function/struct/etc.? Is that correct/sensible? Would you want me to only use the :c:func: stuff in the _first_ mention of a function and then to not use it from then on? I wonder if the _appropriate_ use of :c:func:...: is in the actual definition, but since it's not really practical to do that right now* is simply doing it upon first mention a sensible 'least worst' approach here? Let me know what makes sense! Thanks, Lorenzo *I could add to my TODO to ensure we have at least kerneldoc descriptions for every referenced function, and gradually burn these down as I add them, I just can't guarantee you this will happen any time soon :)
