On Tue, Feb 21, 2017, at 03:13 PM, Bill McCloskey wrote: > I've been thinking about how to integrate documentation into Searchfox. > One > obvious thing is to allow it to display Markdown files and > reStructuredText. I wonder if it could do something useful with Doxygen > comments though? Is this something people would be interested in?
I think an amazing thing searchfox could do would be to make it easier to find the useful documentation that exists. Having joined the platform team with a somewhat pessimistic guess at the amount of useful documentation, I've been pleasantly surprised by what's available. However, it's not always easy to know where the documentation is for code until you've spent a lot of time with it, especially with the amount of plumbing code we have with IPC. That arguably defeats some of the benefit of the docs. For example, when looking at a C++ method and trying to understand what its purpose is/why it's doing something, there could be useful comments: - Preceding the C++ definition or just inside the method. - Preceding the C++ declaration. - Preceding the .idl definition of the method. - Preceding the webidl definition of the method. - In the spec that gives us the webidl definition. - Related to another method that's just a thin wrapper around the method we're looking at. (And which can be pierced by hints or following the call-graph with heuristics like noticing the callee's name is within some edit distance of the caller's name and the caller does very little else, or that the caller just seems to set up a runnable, etc.) - Referenced by in-tree overview markdown docs like devtools has in http://searchfox.org/mozilla-central/source/devtools/docs - Referenced by in-tree overview pandoc docs like SpiderMonkey has in http://searchfox.org/mozilla-central/source/js/src/doc (and which are reflected to MDN) - Referenced by in-tree sphinx-friendly docs that are reflected to https://gecko.readthedocs.io/en/latest/ - Referenced/documented by something on wiki.mozilla.org - Referenced/documented by something on developer.mozilla.org (ignoring) A sketch first steps implementation would be: - Have the file indexers use heuristics to detect block comments and associate them with the following definition/declaration. (Maybe the clang AST already does this?) No need to try and parse the doxygen at first, just be able to display it in a human-readable fashion. Log the comment plus its kind (decl, def, idl, etc.). Well, maybe bless a few things like @see/@sa or @related to allow explicit doc-references to other identifiers to exist. - Aggregate a "docs" file similar to "crossrefs" that stores per-identifier doc links and excerpts. - Do not bake the comments into the syntax-highlighted source to avoid combinatorial explosion. - Have router.py expose an API to lookup the documentation associated with one or more identifiers, possibly following inheritance (when implemented in searchfox) and override relationships as appropriate. - Have hovering over a symbol prefetch/cache the docs for a symbol. - Transform the menu displayed when clicking on a symbol to a mega menu (a la http://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown). Have a top-level entry displaying hints about what docs are available, like "Docs (h idl webidl...)" or greyed out "No Docs". Have the expanded submenu be the excerpts displayed right there so they can be read in their entirety if they're terse. The goal is that the user doesn't need to click through to a full docs search or to follow the links to the docs to read them unless they want to. This idiom could also be used for inheritance information and overrides. Andrew _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
