Request: in identifier search, mark where the kernel-doc is

[cxw42]

Thank you for this tool, which is incredibly useful!! I have a request. An example of the situation:

• In the case of https://elixir.bootlin.com/linux/v5.4.1/ident/bus_find_device , the kernel-doc comments for bus_find_device are in the implementation file, drivers/base/bus.c.
• In the case of https://elixir.bootlin.com/linux/v5.4.1/ident/v4l2_ctrl_query_fill , the kernel-doc comments for v4l2_ctrl_query_fill are in the header file, include/media/v4l2-common.h.

From the search results for an identifier, I am not able to tell which result has the kernel-doc comments. Therefore, I have to find the comments by trial and error between the header and implementation file(s).

Would it be possible for elixir to mark the location of the kernel-doc comments in the ident/foo search results? E.g., what if the results looked like this?---

drivers/media/v4l2-core/v4l2-common.c, line 66 _(as a function)
include/media/v4l2-common.h, line 94 (as a prototype) (doc)

(with the "(doc)" link pointing to the first line of the doc comments)

Thank you for considering this request!

[michaelopdenacker]

Hi.
Many thanks for the suggestion. Though not trivial to implement, this should definitely be helpful.
I'll keep this open until we can come up with a solution.
Thanks again :)
Michael

[cxw42]

Michael, thanks! In case I get some time to work on this, could you give me any initial thoughts as to which files might need to change, or where I might start?

[michaelopdenacker]

Hi Chris,

The way Elixir is architectured doesn't make things very easy... Here's a rough description of how it could be implemented

• In update.py (when new source objects are parsed), detect documentation for symbols, and store such information in a new database file (indexed per symbol and version).
• Modify the query.py back-end to support returning documentation references too. I guess it will be easier to create a new | Documented in" section for documentation in symbol search results, between "Defined in" and "Referenced in". Keep in mind that there could be multiple documentation results, especially if the same symbol is found with the same name in two unrelated parts of the kernel code.
• Modify http/web.py and api/api.py front-end to return the new documentation references.

So, that's not trivial, but of course doable. Don't hesitate to propose a simpler idea :)
Thanks for proposing your help!
Cheers,
Michael.

[cxw42]

I have a rough cut working! Not yet tested, and definitely not yet cleaned up for a PR :) . https://github.com/cxw42/elixir/tree/local-server

[michaelopdenacker]

Hi Chris,
Thanks for sharing this snapshot (though I don't have overlay-loader.c in my kernel tree...). At least I know what it would look like :)
Please, don't hesitate to submit a PR when you're ready. I'll be happy to test it.
Many thanks,
Michael

[michaelopdenacker]

Hi Chris (@cxw42)

FYI, https://elixir.bootlin.com now is running with a freshly generated database with documentation information. Switching to a web front-end exposing such information will just take minutes ;-)

Michael

[cxw42]

I was thinking just yesterday that I had better get my PR in for the front end now that Maxime is on the job :) .

[cxw42]

I have a branch going with an initial test framework for web.py. I'm doing TDD on this one :) .
PR to follow in due course. https://github.com/cxw42/elixir/tree/webtest

[cxw42]

I have added tests of the doc-comment front end and cxw42@29ce0f0 passes the tests! @MaximeChretien would you please give it a try and let me know how it goes? I will squash before submitting the PR. Thanks!

[MaximeChretien]

Hi @cxw42

I merged it on top of #130 , everything seems to work fine for me, both tests and web interface work without problems.

But I noticed some things :

• Docs for enum, struct and define doesn't seems to be indexed :
  https://elixir.bootlin.com/linux/latest/source/include/linux/memblock.h#L28
  https://elixir.bootlin.com/linux/latest/source/include/linux/memblock.h#L42
  https://elixir.bootlin.com/linux/latest/source/include/linux/memblock.h#L148

Maybe it would be great to add that ? What do you think @michaelopdenacker ?

• Docs seems to be missing for that function (and probably other too) :
  https://elixir.bootlin.com/linux/latest/source/include/linux/memblock.h#L463

I'll continue to do some tests and I'll tell you if I find something else ;)

[cxw42]

Much appreciated! I'll try out those cases. My original thought was to detect all kernel-doc, not just functions, but maybe I missed something.

[cxw42]

After commenting above, I looked at #130 and I see that it switches from exuberant to universal ctags. It may be that the ctags-output parser in find-file-doc-comments.pl needs some updates to be able to accept universal's output. I will investigate.

[cxw42]

Nope --- it's just that find-file-doc-comments.pl only extracts function docs! Would you like to do the current release with just functions, then add the rest later?

[MaximeChretien]

Hi,
Yes you can send the current release with just functions docs and add the rest later when you have time
Thanks :D