search

bootlin / elixir

The Elixir Cross Referencer
GNU Affero General Public License v3.0
966 stars 143 forks source link

Linux kernel-internals man-pages view of the database? [Documentation] [Long term] #215

Open cxw42 opened 3 years ago

cxw42 commented 3 years ago

It just occurred to me that we could take the Documented in links for each version and render an index of the documentation pages. This would, in essence, become a set of man pages for the kernel internals for that version \o/ . This is just an idea --- any thoughts or interest?

michaelopdenacker commented 3 years ago

Hi Chris Thanks for the suggestion ! Actually, wouldn't it be a kernel documentation issue instead, that we should address using Sphinx? Indeed, it would be nice to have a symbol index, such as the one we have in the Yocto Project: https://docs.yoctoproject.org/genindex.html Cheers

cxw42 commented 3 years ago

Yes, the Yocto symbol index is the kind of thing I am thinking of.

If this could be addressed with Sphinx, that would be great! I do not know enough Sphinx to know how.

fstachura commented 3 weeks ago

I found this https://docs.kernel.org/genindex.html This for older versions https://www.kernel.org/doc/html/

I compared index for latest with what I have in my database after indexing Linux, and it seems that Elixir finds much more doccoments than what's available in genindex. I'm not sure if that's on purpose, I was unable to find an explanation. It seems that many doccoments related to optional things are missing. For example, ntfs_mapping_pairs_decompress and other prefixed with ntfs_, same with nfp_ , acpi_ , binder_ and many others.

Diff between a list of indexed doccoments and symbols from genindex (note that the database spans versions from v3.1 to v6.9.4 and I'm comparing that with the latest genindex. laziness on my part because reindexing a single Linux version will take long, but that still brings up many, many examples of symbols available in Elixir v6.11-rc4 but not in related genindex, easy to check by comparing search results from Elixir and from the genindex. I can do a proper comparison if it's necessary). Code

tleb commented 2 weeks ago

I have never digged into this. There are some special .. kernel-doc:: blocks inside Documentation/***.rst files that might be part of the explanation. See Documentation/core-api/kernel-api.rst as example.

The preprocessor might be another part of the explanation. Take for example clk_bulk_prepare. Its prototype is in include/linux/clk.h. Most prototypes in this file are documented, but not clk_bulk_prepare that is behind a #ifdef CONFIG_HAVE_CLK_PREPARE.

Does that help?

fstachura commented 2 weeks ago

I was more trying to see if this functionality could be useful in any way. Since the index in the docs does not contain all documented symbols then maybe? But also maybe there is an actual reason why these symbols are missing.

But it's good to know that files that are supposed to be indexed have to be explicitly linked from docs.