Re: [PATCH v3 bpf-next 2/2] bpf, docs: document BPF_MAP_TYPE_ARRAY

[Jonathan Corbet <corbet@lwn.net>]

"Dave Tucker" <dave@dtucker.co.uk> writes:

> On Tue, 7 Dec 2021, at 14:53, Jonathan Corbet wrote:
>> Dave Tucker <dave@dtucker.co.uk> writes:
>>
>>> This commit adds documentation for the BPF_MAP_TYPE_ARRAY including
>>> kernel version introduced, usage and examples.
>>> It also documents BPF_MAP_TYPE_PERCPU_ARRAY since this is similar.
>>>
>>> Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
>>> ---
>>>  Documentation/bpf/map_array.rst | 182 ++++++++++++++++++++++++++++++++
>>>  1 file changed, 182 insertions(+)
>>>  create mode 100644 Documentation/bpf/map_array.rst
>>
>> When you add a new file, you need to add it to index.rst as well to
>> bring it into the docs build.
>
> I believe I responded to this comment in an earlier version of this patch set.
> The glob pattern in Documentaion/bpf/maps.rst includes this in the docs build.

Sorry...I even looked for :glob:, believe it or not, but not in
linux-next, sorry.  Caffeine is taking effect now...

>> It's really better not to use ``literal markup`` for function names.
>> Just write function() and the right thing will happen, including
>> cross-reference links to the kerneldoc for that function if it exists.
>
> I've just tested this out, and for some reason it's not working as expected.
> It's not formatted as ``literal markup`` nor is it linked to kerneldoc.
> Perhaps because the issue is because these are part of tools/lib/bpf/bpf_helpers.h?

It can only link to kerneldoc that's actually pulled into the built
documentation.  If there isn't a ".. kernel-doc::" directive for that
file (and it appears there is not) then Sphinx doesn't know about it.

Thanks,

jon