[tor-commits] [tor/master] Add documentation about building a TAGS file.

[nickm at torproject.org]

commit e08d07692fa7f2dd0cd139cb0c7e359be4264d8a
Author: Nick Mathewson <nickm at torproject.org>
Date:   Mon Jan 6 13:31:30 2020 -0500

    Add documentation about building a TAGS file.
    
    Patch from opara.  Closes ticket 32779.
---
 changes/ticket32779         |  3 +++
 doc/HACKING/HelpfulTools.md | 24 ++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/changes/ticket32779 b/changes/ticket32779
new file mode 100644
index 000000000..1b7ccaa7e
--- /dev/null
+++ b/changes/ticket32779
@@ -0,0 +1,3 @@
+  o Documentation:
+    - Add documentation in 'HelpfulTools.md' to describe how to build a tag
+      file. Closes ticket 32779.
diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md
index cba57e875..866b32128 100644
--- a/doc/HACKING/HelpfulTools.md
+++ b/doc/HACKING/HelpfulTools.md
@@ -315,6 +315,30 @@ If you use emacs for editing Tor and nothing else, you could always just say:
 There is probably a better way to do this.  No, we are probably not going
 to clutter the files with emacs stuff.
 
+Building a tag file (code index)
+--------------------------------
+
+Many functions in tor use `MOCK_IMPL` wrappers for unit tests. Your
+tag-building program must be told how to handle this syntax.
+
+If you're using emacs, you can generate an emacs-compatible tag file using
+`make tags`. This will run your system's `etags`. Tor's build system assumes
+that you're using the emacs-specific version of `etags` (bundled under the
+`xemacs21-bin` package on Debian). This is incompatible with other versions of
+`etags` such as the version provided by Exuberant Ctags.
+
+If you're using vim or emacs, you can also use Universal Ctags to build a tag
+file using the syntax:
+
+    ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' .
+
+If you're using an older version of Universal Ctags, you can use the following
+instead:
+
+    ctags -R --mline-regex-c='/MOCK_IMPL\([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' .
+
+A vim-compatible tag file will be generated by default. If you use emacs, add
+the `-e` flag to generate an emacs-compatible tag file.
 
 Doxygen
 -------