commit 927e82fdf7c052d95890f97f747a1ecb6d3b56cf parent 9451691a420734a97d19391aca8eb345efb375a8 Author: Tooru Fujisawa <arai_a@mac.com> Date: Wed, 26 Nov 2025 04:05:20 +0000 Bug 2001826 - Add documentation for Searchfox. r=asuth Differential Revision: https://phabricator.services.mozilla.com/D273742 Diffstat:
20 files changed, 501 insertions(+), 1 deletion(-)
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst @@ -18,7 +18,7 @@ development process and source code documentation. data-collection data-review jujutsu - searchfox/searchfox_search + searchfox ai-coding diff --git a/docs/contributing/searchfox.rst b/docs/contributing/searchfox.rst @@ -0,0 +1,41 @@ +========= +Searchfox +========= + +`Searchfox <https://searchfox.org/>`__ is a source code indexing tool for Mozilla Firefox. It indexes C++. Rust, JavaScript, Python, Java, and some other code. + +.. toctree:: + :maxdepth: 1 + + searchfox/searchfox_search + searchfox/source_listing + searchfox/context_menu + searchfox/navigation_panel + searchfox/blame + searchfox/backend + +Repositories +============ + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - `mozsearch <https://github.com/mozsearch/mozsearch>`__ + - The main source code of the Searchfox website. + + * - `mozsearch-mozilla <https://github.com/mozsearch/mozsearch-mozilla>`__ + - The Mozilla-specific config for Searchfox. + +Get Involved +============ + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - `#searchfox:mozilla.org <https://chat.mozilla.org/#/room/#searchfox:mozilla.org>`__ + - Matrix chat room + + * - `Good first bugs <https://codetribute.mozilla.org/projects/searchfox>`__ + - List of bugs suitable for newcomers diff --git a/docs/contributing/searchfox/backend.rst b/docs/contributing/searchfox/backend.rst @@ -0,0 +1,5 @@ +======= +Backend +======= + +The backend documentation can be found in `the mozsearch repository <https://github.com/mozsearch/mozsearch/tree/master/docs>`__. diff --git a/docs/contributing/searchfox/blame.rst b/docs/contributing/searchfox/blame.rst @@ -0,0 +1,34 @@ +.. _searchfox-blame: + +===== +Blame +===== + +"Blame" (in git, or "annotate" in mercurial) is a feature to show the last revision that modified the line, for each line in a file. The blame information is embedded into the source listing. + +.. image:: img/blame.png + :class: border + :alt: The blame popup + :width: 683px + + +.. _searchfox-blame-strip: + +Blame strip +----------- + +The blame information is available from the blame strip, which is shown at the left side of the line numbers, as a gray line. Hovering a pointer over the blame strip shows a "blame popup", which shows the blame information for the given chunk of the code. + +The first two lines show the commit mssage, usually starts from the bug number, and then the author, and the author date (not the committer/push date). + +annotated diff + Open the annotated diff view of the commit, hosted on Searchfox. + +full diff + Open the full diff view on the repository, e.g. on `hg.mozilla.org`. + +Show latest version without this line + Open the revision-specific URL of the last revision before the given commit. + +Show earliest version with this line + Open the revision-specific URL of the revision for the given commit. diff --git a/docs/contributing/searchfox/context_menu.rst b/docs/contributing/searchfox/context_menu.rst @@ -0,0 +1,144 @@ +.. _searchfox_context_menu: + +============ +Context Menu +============ + +Searchfox provides a custom context menu, which is opened on the primary button click (not the secondary button click, which is for the browser's built-in context menu). + +Clicking symbols, such as function name or variable name shows a context menu for the clicked symbols. + +.. image:: img/context-menu.png + :class: border + :alt: The context menu for symbols + :width: 428px + +Symbols +------- + +Go to definition of ... + Open the definition of given symbol. + + This is shown for the consumers of functions, variables. + +Go to declaration of ... + Open the forward declaration of given function. + +Search for ... + Open the search result of given symbol. + + The search result will include the definition, declaration, and uses. + +Search for the substring ... + Open the search result of given substring. + +Sticky highlight + Keep applying the highlight on the symbol. + + This is useful for example when you're scrolling through the function while highlighting one of the function arguments. + +Structured Analysis +------------------- + +For bindings generated by XPIDL and WebIDL, Searchfox generates structured analysis, which associates these C++ symbol, JavaScript symbol, generated binding, etc. + +.. image:: img/context-menu-idl-1.png + :class: border + :alt: The context menu for WebIDL definitions + :width: 678px + +.. image:: img/context-menu-idl-2.png + :class: border + :alt: The context menu for WebIDL generated bindings + :width: 538px + +Go to IDL definition ... + Open the definition inside the XPIDL/WebIDL file for given interface etc. + +Go to definition of IDL C++ binding ... + Open the auto-generated binding for given method or attribute. + +Search for IDL JS ... + Open the search result of given symbol in JS files. + +Search for IDL C++ binding ... + Open the search result of given auto-generated binding. + +Search for IDL ... + Open the search result of all symbols related to the IDL definition, including the JS symbol and C++ bindings. + +Macro expansion +--------------- + +For preprocessor macros inside C/C++ code, Searchfox can show the expansion result, possibly for each compilation target. + +.. image:: img/context-menu-macro-1.png + :class: border + :alt: The context menu for macros + :width: 673px + +Expansion on ... + Open a macro expansion popup for given compilation target + + .. image:: img/context-menu-macro-2.png + :class: border + :alt: The macro expansion popup + :width: 636px + +Class field layout +------------------ + +For C++ classes, Searchfox can show the field layout table for each compilation target. + +This is behind the alpha feature gate "Semantic Info Queries". + +.. image:: img/context-menu-layout.png + :class: border + :alt: The context menu for classes + :width: 448px + +Class layout of ... + Open the class field layout table of given class. + + This item is shown on the classes which has the class field layout information. + +Diagrams +-------- + +For functions, classes, methods, and fields, Searchfox can show the diagram of how they're used, called, or related. + +These items are behind the alpha feature gate "Diagramming". + +Uses diagram of ... + Open a diagram that shows how given field is used. + +Calls diagram of ... + Open a diagram that shows how given function is called. + +Class diagram of ... + Open a diagram that shows given class and its fields, the hierarchy, etc. + +Inheritance diagram of ... + Open a diagram that shows the class hierarchy of given class. + +Go to use of ... + Open the use site of the function shown as the edge in the diagram. + + This item is shown for the uses diagram's edge. + +GC analysis +----------- + +For functions that uses SpiderMonkey JSAPI, Searchfox can show which function can perform GC. +See the `Static Analysis for Rooting and Heap Write Hazards <https://firefox-source-docs.mozilla.org/js/HazardAnalysis/index.html>`__ document for more details how the analysis works. + +This is behind the alpha feature gate "Semantic Info Queries". + +Can GC/Cannot GC + If a function can perform GC, "Can GC" item is shown. + Clicking this shows a possible call path to the GC. + + If a function can never perform GC, "Cannot GC" item is shown. + + If the function is not found in the hazard analysis data, neither of these items are shown. + This can happen if the function is not covered by the hazard analysis, or if the function symbol differs between GCC and Clang. diff --git a/docs/contributing/searchfox/img/blame.png b/docs/contributing/searchfox/img/blame.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu-idl-1.png b/docs/contributing/searchfox/img/context-menu-idl-1.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu-idl-2.png b/docs/contributing/searchfox/img/context-menu-idl-2.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu-layout.png b/docs/contributing/searchfox/img/context-menu-layout.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu-macro-1.png b/docs/contributing/searchfox/img/context-menu-macro-1.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu-macro-2.png b/docs/contributing/searchfox/img/context-menu-macro-2.png Binary files differ. diff --git a/docs/contributing/searchfox/img/context-menu.png b/docs/contributing/searchfox/img/context-menu.png Binary files differ. diff --git a/docs/contributing/searchfox/img/coverage.png b/docs/contributing/searchfox/img/coverage.png Binary files differ. diff --git a/docs/contributing/searchfox/img/navigation-panel-collapsed.png b/docs/contributing/searchfox/img/navigation-panel-collapsed.png Binary files differ. diff --git a/docs/contributing/searchfox/img/navigation-panel-symbol.png b/docs/contributing/searchfox/img/navigation-panel-symbol.png Binary files differ. diff --git a/docs/contributing/searchfox/img/navigation-panel.png b/docs/contributing/searchfox/img/navigation-panel.png Binary files differ. diff --git a/docs/contributing/searchfox/img/nesting.png b/docs/contributing/searchfox/img/nesting.png Binary files differ. diff --git a/docs/contributing/searchfox/img/source-listing.png b/docs/contributing/searchfox/img/source-listing.png Binary files differ. diff --git a/docs/contributing/searchfox/navigation_panel.rst b/docs/contributing/searchfox/navigation_panel.rst @@ -0,0 +1,218 @@ +================ +Navigation Panel +================ + +The navigation panel provides various features for the current file. + +.. image:: img/navigation-panel.png + :class: border + :alt: The navigation panel + :width: 319px + +In the directory listing and some other cases, the navigation panel is collapsed by default. +Clicking the triangle icon at the left end expands/collapses the navigation panel. + +.. image:: img/navigation-panel-collapsed.png + :class: border + :alt: The navigation panel in a closed state + :width: 246px + + +Source code +----------- + +This section provides feature related to the current file. + +Go to header file/Go to source file + Open the corresponding source or header file. + + This item is shown if the current file is C++ source (``.cpp``, ``.cc``, ``.cxx``) or header file (``.h``, ``.hh``, ``.hpp``, ``.hxx``) and there's corresponding source or header file exists. + +File a bug in ... + Open the Bugzilla new bug page for the associated Bugzilla component. + + This item is shown whwn the current file/directory has an associated Bugzilla component. + +Revision control +---------------- + +This section provides feature related to the VCS. + +Permalink + Convert the current document's URL into a revision-specific URL. + + This item is shown when opening a revision-agnostic URL. + + For example, if you click the item while you're on ``https://searchfox.org/firefox-main/source/js/src/jsapi.h``, It converts the current URL into ``https://searchfox.org/firefox-main/rev/3f22e78e34249196edab0a5b756394169533b8a1/js/src/jsapi.h`` (the revision ID part depends on the latest revision at that point.) + + The former URL shows the file content of the latest revision at the point of opening the page, and the latter URL shows the file content of the given revision. + + Searchfox index is updated twice a day for the main branches, and this means the file content can change twice a day. This URL is handy for sharing the code in bug comments or in chat, where people can open the link later. + + This item has associated shortcut key :kbd:`Y`, and hitting the :kbd:`Y` key also does the same. + + Clicking the "Copy to clipboard" button next to this copies the permalink into your clipboard. + + See the :ref:`searchfox-copy-as-markdown` section below for more info about sharing code or reference. + +Remove the Permalink + Convert the current document's URL into a revision agnostic URL. + This is the opposite operation of the "Permalink" above. + + This item is shown when opening a revision-specific URL, where the revision is the latest revision. + +Go to latest version + Opens the revision-agnostic URL of the current file. + + This item is shown when opning a revision-specific URL, where the revision is not the latest revision. + +Git log + Open the log of the current file on GitHub. + + This item is shown when the current repository is hosted on GitHub. + +Mercurial log + Open the log of the current file on ``hg.mozilla.org``. + Hitting the :kbd:`L` key also does the same. + + This item is shown when the current repository is hosted on ``hg.mozilla.org``. + +Raw + Open the raw file of the current file. + + This is shown when the repository has a raw file link. + +Blame + This is just a placeholder. + The blame information is shown in the :ref:`Blame strip <searchfox-blame-strip>`. + +Show changeset + Open the changeset information for the current diff, hosted on Searchfox. + + This item is shown on the annotated diff view. + (See :ref:`Blame <searchfox-blame>` for the link for the annotated diff view.) + + +Show file without diff + Open a revision-specific URL of the current file before the current diff is applied. + + This item is shown on the annotated diff view. + (See :ref:`Blame <searchfox-blame>` for the link for the annotated diff view.) + +Symbol +------ + +.. image:: img/navigation-panel-symbol.png + :class: border + :alt: The navigation panel Symbol section + :width: 362px + +This is behind the alpha feature gate "Fancy Bar". + +This section shows the currently-selected symbol's qualified name. + +This provides a button to copy the qualified name to clipboard. + +.. _searchfox-copy-as-markdown: + +Copy as Markdown +---------------- + +This section provides a feature to copy the selected file/symbol/code as Markdown. +This is handy for sharing the reference in bug comments or in chat. + +Filename Link + Copy the current file's revision-specific URL, with the filename, as Markdown. + Hitting the :kbd:`F` key also does the same. + + + For example, if you're on ``https://searchfox.org/firefox-main/source/js/src/jsapi.h#107``, clicking this copies the following text to clipboard. + + .. code-block:: + + [jsapi.h](https://searchfox.org/firefox-main/rev/3f22e78e34249196edab0a5b756394169533b8a1/js/src/jsapi.h#107) + +The link includes the currently-selected lines. + +Symbol Link + Copy the current file's revision-specific URL, with the currently-selected symbol, as Markdown. + Hitting the :kbd:`S` key also does the same. + + For example, if you're on ``https://searchfox.org/firefox-main/source/js/src/jsapi.h#128`` where the line has ``JS::InformalValueTypeName`` function declaration, clicking this copies the following text to clipboard. + + .. code-block:: + + [JS::InformalValueTypeName](https://searchfox.org/firefox-main/rev/3f22e78e34249196edab0a5b756394169533b8a1/js/src/jsapi.h#128) + + The link includes the currently-selected lines. + +Code Block + Copy the currently-selected lines as a Markdown code block. + Hitting the :kbd:`C` key also does the same. + + This is handy for sharing the code in a bug comment, while explaining the execution flow. + + For example, if you're on ``https://searchfox.org/firefox-main/source/js/src/vm/JSObject.cpp#115-119,136-141`` page, where multiple lines are selected, clicking this copies the following text to clipboard. + + .. code-block:: + + https://searchfox.org/firefox-main/rev/3f22e78e34249196edab0a5b756394169533b8a1/js/src/vm/JSObject.cpp#115-119,136-141 + ```cpp + JS_PUBLIC_API const char* JS::InformalValueTypeName(const Value& v) { + switch (v.type()) { + case ValueType::Double: + case ValueType::Int32: + return "number"; + ... + case ValueType::PrivateGCThing: + break; + } + + MOZ_CRASH("unexpected type"); + } + ``` + +Other Tools +----------- + +This section shows links to externsion tools. + +HG Web + Open the the current file on ``hg.mozilla.org``. + + This item is shown when the current repository is hosted on ``hg.mozilla.org``. + +Code Coverage + Open the code coverage result of this file. + + This item is shown when the current file has code coverage result. + +Source Docs + Open the rendered view of the current file on ``https://firefox-source-docs.mozilla.org/``. + + This item is shown when the current file is a document file (``.md`` or ``.rst``) for Firefox Source Docs. + +GitHub Rendered view + Open the rendered view of the current file on GitHub. + + This item is shown when the current file is a document file. + +Debug +----- + +This section is behind the "Show debugging UI" setting. + +Raw analysis records + Open a raw analysis file for the current file. + + This item is shown when opening a file. + +Show debug log/Hide debug log + Show/hide the debug log of the current query. + + This item is shown in the query endpoint. + +Show results JSON/Hide results JSON + Show/hide the raw JSON of the current query result. + + This item is shown in the query endpoint. diff --git a/docs/contributing/searchfox/source_listing.rst b/docs/contributing/searchfox/source_listing.rst @@ -0,0 +1,58 @@ +============== +Source listing +============== + +.. image:: img/source-listing.png + :class: border + :alt: The source listing and each component + :width: 958px + +Breadcrumbs +----------- + +At the top of the source listing, breadcrumbs for the file is shown. + +You can select different tree from the repository drop down menu there, and also navigate to other directory, or open a context menu for the file symbol. + +Line numbers +------------ + +Lines can be selected by clicking, optionally with modifier keys. The selected lines are reflected to the URL, and opening URLs with those lines shows the selected lines. + +This is handy for sharing a code with pointing specific lines. + + * Click the line number selects the line. + * :kbd:`Shift` + click: selects lines by start/end range. + * :kbd:`Ctrl` + click / :kbd:`Cmd` + click: adds/removes individual line from/to the selection. + +Blame strip +----------- + +See the :ref:`Blame strip <searchfox-blame-strip>` documentation. + +Code coverage +------------- + +The light-blue line next to the blame strip shows the `code coverage <https://firefox-source-docs.mozilla.org/tools/code-coverage/index.html>`__ information. + +Hovering a pointer over the coverage strip shows a coverage popup, which shows how many times the line is hit in the automation. + +.. image:: img/coverage.png + :class: border + :alt: The code coverage information + :width: 589px + +Nesting header +-------------- + +.. image:: img/nesting.png + :class: border + :alt: The nesting header + :width: 535px + +For nesting structures inside a source code, such as namespaces, classes, functions, etc, Searchfox shows a sticky header for the nesting. + +Symbols +------- + +Clicking each symbol (functions, variables) opens :ref:`Context menu <searchfox_context_menu>`.
