On Tue, Jun 03, 2025 at 09:05:32AM -0600, Jonathan Corbet wrote: > Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx> writes: > > > 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. > > So far so good > > > 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. > > If you just drop the "!" you'll run into the "struct" problem you > mentioned before. You'll need to take out "struct" as well if you go > this route... Yeah I will do so... > > > - Perhaps hack in a **struct ** prefix so we get the 'best of both worlds' > > on this for types...? > > ...so yes you'd need to do that. ...with this hack as needed :) > > > 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? > > Here, I think, we've gone a bit off track again. The goal of the > automarkup code was to *never* need to use the :c:func: markup. Let's > just say that ... certain members of our community ... found that markup > entirely intolerable - and, in truth, it is ugly. So I wrote the > initial automarkup extension; now, any time that the docs build sees > function(), it looks for documentation for that function and creates a > cross-reference if that documentation is found. > > The goal is that you should never need the :c:gunk: ever. > > Thanks, > > jon OK thanks for clarifying, so let's do a take 2 of the action items: 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-. 4. Drop '!' from every reference so we get automated cross-referencing (with the ** struct ** hack as needed). 5. Where possible see if we have functions documented, and if so avoid the :c:... noise. If we can't avoid it for now, note down the functions and add to todo to get documented. We can remove the gunk as we go... A couple questions on point 5: - When you say 'documentation', do you mean the /** kernel-doc stuff? - Does running `make SPHINXDIRS=mm htmldocs` suffice to have this script run? As this is how I've been previewing my changes so far! Thanks, Lorenzo
