diagramming.rst (8213B)
1 .. _searchfox_diagramming: 2 3 =========== 4 Diagramming 5 =========== 6 7 The diagramming feature provides generating diagrams for calls/uses relations, classes and their inheritances. 8 9 The diagramming feature can be accessed from two ways. 10 11 * :ref:`Context menu <searchfox_diagramming_context_menu>` 12 * :ref:`Query endpoint <searchfox_diagramming_queries>` 13 14 **Enabling Diagramming**: To use diagramming features, visit the `settings page 15 <https://searchfox.org/mozilla-central/pages/settings.html>`_ and change the 16 "Default feature gate" from "Release" to "Alpha", or use the "Diagramming 17 feature gate" setting. 18 19 **Language Support**: Diagramming currently works for C++ and languages with 20 SCIP indexing support (Java/Kotlin/Python), but not JavaScript/TypeScript. 21 22 **Accessibility Note**: The diagrams currently do not generate a usable 23 accessibility tree and are considered alpha quality. 24 25 .. image:: img/diagramming.png 26 :class: border 27 :alt: The diagramming feature 28 :width: 573px 29 30 .. _searchfox_diagramming_context_menu: 31 32 Context Menu 33 ------------ 34 35 .. image:: img/context-menu-layout.png 36 :class: border 37 :alt: The context menu for classes 38 :width: 448px 39 40 Uses diagram of ... 41 Open a diagram that shows how given field is used. 42 43 Calls diagram of ... 44 Open a diagram that shows how given function is called. 45 46 Class diagram of ... 47 Open a diagram that shows given class and its fields, the hierarchy, etc. 48 49 Inheritance diagram of ... 50 Open a diagram that shows the class hierarchy of given class. 51 52 Context Menu for nodes 53 ^^^^^^^^^^^^^^^^^^^^^^ 54 55 .. image:: img/diagramming-menu-node.png 56 :class: border 57 :alt: The context menu for nodes 58 :width: 446px 59 60 Ignore this node in the diagram 61 Re-generate the diagram, ignoring the specified node. 62 63 Context Menu for edges 64 ^^^^^^^^^^^^^^^^^^^^^^ 65 66 .. image:: img/diagramming-menu-edge.png 67 :class: border 68 :alt: The context menu for edges 69 :width: 426px 70 71 Go to use of ... 72 Open the use site of the function shown as the edge. 73 74 .. _searchfox_diagramming_queries: 75 76 Controls 77 -------- 78 79 In the diagramming page, the breadcrumbs contains the "Diagram Controls" button. 80 81 The control panel allows customizing the query. 82 83 The number of nodes are limited by default. If the limit is hit, warning messages are shown, with buttons to lift the limit if possible. 84 85 The Legend section shows the meaning of the badges (e.g. "💪"), which can be added to the nodes for annotation purposes. 86 87 .. image:: img/diagramming-control.png 88 :class: border 89 :alt: The control panel 90 :width: 919px 91 92 Depth 93 Limit graph traversal to N levels of depth (1-based). 94 95 Corresponds to the ``depth:N`` parameter. 96 97 Node limit 98 Maximum nodes in resulting graph. 99 100 Corresponds to the ``node-limit:N`` parameter. 101 102 Path limit 103 Nodes with more than N in-edges will be excluded (default: 96) 104 105 For "Calls between", this is maximum nodes for path-finding algorithm 106 107 Corresponds to either the ``path-limit:N`` or the 108 ``paths-between-node-limit:N`` parameter. 109 110 Ignore nodes 111 A comma-separated list of pretty symbols for the nodes to exclude from the diagram. 112 113 This can be added by the "Ignore this node in the diagram" context menu item. 114 115 Corresponds to the ``ignore-nodes:LIST`` parameter. 116 117 Hierarchy 118 Controls the hierarchy and the styling of the diagram. 119 120 Simple no hierarchy 121 Disable hierarchy, use old flat layout (``hier:flat``) 122 123 No hierarchy 124 Disable hierarchy but applies other styling, such as badges (``hier:flatbadges``) 125 Pretty identifier hierarchy 126 Default hierarchy based on pretty symbol name (``hier:pretty``) 127 128 Subsystem and class structures: 129 Group by bugzilla component mapping (``hier:subsystem``) 130 131 Full file paths 132 Fine-grained file-level hierarchy (``hier:file``) 133 134 Directories 135 Group by directories (``hier:dir``) 136 137 Layout 138 Select the layout algorithm. 139 140 dot 141 Default orderly layout (recommended) (``graph-layout:dot``) 142 143 neato 144 Force-directed layout for less orderly appearance (``graph-layout:neato``) 145 146 fdp 147 Force-directed with variable edge lengths (``graph-layout:fdp``) 148 149 Format 150 Select the output format of the graph. 151 Options other than "SVG and symbols" are mostly for debugging purpose. 152 153 JSON 154 Prints the raw input JSON data for the graph (``graph-format:json``) 155 156 SVG 157 Shows only the generated SVG (``graph-format:svg``) 158 159 dot with layout 160 Prints the raw "dot" input data, with the layout information (``graph-format:dot``) 161 162 dot without layout 163 Prints the raw "dot" input data, without the layout information ( ``graph-format:raw-dot`` 164 165 SVG and symbols 166 Show the generated SVG, annotated with the symbol information ``graph-format:mozsearch`` 167 168 Debug 169 When checked, show the debug log. 170 171 Queries 172 ------- 173 174 **Important**: These diagramming features use the ``/query`` endpoint, not 175 ``/search``. If you type this syntax in the regular search box, it won't work. 176 177 Inheritance diagram 178 ^^^^^^^^^^^^^^^^^^^ 179 180 :: 181 182 inheritance-diagram:'nsIInputStream' depth:4 183 184 https://searchfox.org/mozilla-central/query/default?q=inheritance-diagram%3A%27nsIInputStream%27%20depth%3A4 185 186 Class diagram 187 ^^^^^^^^^^^^^ 188 189 :: 190 191 class-diagram:'mozilla::GraphDriver' depth:3 192 193 https://searchfox.org/mozilla-central/query/default?q=class-diagram%3A%27mozilla%3A%3AGraphDriver%27+depth%3A3 194 195 Function call diagram 196 ^^^^^^^^^^^^^^^^^^^^^ 197 198 This works both directions. 199 200 :: 201 202 calls-from:'mozilla::dom::AudioContext::CreateDynamicsCompressor' depth:2 203 calls-to:'mozilla::dom::AudioContext::CreateDynamicsCompressor' depth:4 204 205 https://searchfox.org/mozilla-central/query/default?q=calls-from%3A%27mozilla%3A%3Adom%3A%3AAudioContext%3A%3ACreateDynamicsCompressor%27+depth%3A2 206 https://searchfox.org/mozilla-central/query/default?q=calls-to%3A%27mozilla%3A%3Adom%3A%3ADynamicsCompressorNode%3A%3AThreshold%27+depth%3A4 207 208 **Note**: ``calls-from`` now avoids traversing into methods like 209 ``NS_DebugBreak`` that would otherwise clutter diagrams. Similarly, ``calls-to`` 210 and ``calls-between`` avoid problematic interfaces like ``nsIObserver::Observe`` 211 and ``nsISupports`` methods. 212 213 Calls Between 214 ------------- 215 216 The ``calls-between`` functionality allows you to discover how different classes 217 or methods interact with each other. This is particularly useful for 218 understanding complex code relationships. 219 220 This functionality is not yet available in the context menu. 221 222 Basic calls-between 223 ^^^^^^^^^^^^^^^^^^^ 224 225 Find paths between any methods of two classes: 226 227 :: 228 229 calls-between:'mozilla::ProcessPriorityManager' calls-between:'nsTimer' 230 231 https://searchfox.org/mozilla-central/query/default?q=calls-between-source%3A%27mozilla%3A%3AProcessPriorityManager%27%20calls-between-target%3A%27nsTimer%27 232 233 Directional calls-between 234 ^^^^^^^^^^^^^^^^^^^^^^^^^ 235 236 For more precise control, use ``calls-between-source`` and ``calls-between-target``: 237 238 :: 239 240 calls-between-source:'nsDocShell' calls-between-target:'nsExternalHelperAppService' depth:10 241 242 https://searchfox.org/mozilla-central/query/default?q=calls-between-source%3AnsDocShell%20calls-between-target%3AnsExternalHelperAppService%20depth%3A10 243 244 Specific method targeting 245 ^^^^^^^^^^^^^^^^^^^^^^^^^ 246 247 When you know specific methods, you can target them directly: 248 249 :: 250 251 calls-between-source:'nsGlobalWindowInner::SetTimeout' calls-between-source:'nsGlobalWindowInner::ClearTimeout' calls-between-target:'nsTimer' depth:9 252 253 https://searchfox.org/mozilla-central/query/default?q=calls-between-source%3A%27nsGlobalWindowInner%3A%3ASetTimeout%27+calls-between-source%3A%27nsGlobalWindowInner%3A%3AClearTimeout%27+calls-between-target%3A%27nsTimer%27+depth%3A9+paths-between-node-limit%3A12000 254 255 **Note**: You must now provide absolute pretty identifiers. If your class is 256 ``foo::Bar``, you can't just use ``Bar`` - you need the full path to avoid 257 ambiguity. 258 259 Include Graph Visualization 260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 261 262 There's a synthetic "(file symbol)" at the end of file path breadcrumbs. 263 Diagrams triggered on this symbol visualize the header include file graph. This 264 is most useful with ``calls-between`` queries. 265 266 Advanced Options 267 ^^^^^^^^^^^^^^^^ 268 269 - ``fmus-through-depth:N`` - Include "field member uses" for pointer relationships (use 0 for depth 0 nodes only)