kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

On Mon, Nov 26, 2018 at 2:06 PM Wayne Stambaugh <stambaughw@xxxxxxxxx> wrote:

> I did it so I didn't have to grep the entire source tree to find
> the trace string.

Indeed!

> I can see the utility of adding the strings to the trace variable docs.
>  I agree that digging through the source file can be time consuming.

I have added these in the attached patch, and linked to the source
from the testing.md dev docs. (This patch is contingent on the zoom
patches).

> I'm not opposed to defining the doxygen group markers in place but my
> guess is devs will not be consistent about it so the trace_helpers
> header file will ensure they get added to the group.  That is one of the
> reasons I started merging them into a single file.  That process is not
> complete.

Whatever keeps maintenance simpler is best, IMO. I was just noting
that it is not required to define things together to document
together. Will all masks, even in the 3D plugin, which has its own
large set, be in the common include?

> I doubt that compiling will become a huge issue but I could be wrong
> about that.

For now, certainly, it's not a massive issue, especially if you touch
libcommon or Git and invoke a re-link anyway!

Cheers,

John

From 5dc15d908b875e6dbe22a81a5d115d285f812e0e Mon Sep 17 00:00:00 2001
From: John Beard <john.j.beard@xxxxxxxxx>
Date: Mon, 26 Nov 2018 16:25:12 +0000
Subject: [PATCH] Document tracemask strings and add note in testing.md

Also make the examples in the testing.md docs self-consistent.
---
 Documentation/development/testing.md | 10 +++++++---
 include/trace_helpers.h              | 30 +++++++++++++++++++++++++++-
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/Documentation/development/testing.md b/Documentation/development/testing.md
index 7fddb2050..e0c3c04ae 100644
--- a/Documentation/development/testing.md
+++ b/Documentation/development/testing.md
@@ -224,11 +224,14 @@ a "mask", for example:
 This will not be printed by default. To show it, set the `WXTRACE` environment
 variable when you run KiCad to include the masks you wish to enable:
 
-    $ WXTRACE="TRACEKEY,OTHERKEY" kicad
+    $ WXTRACE="TRACEMASK,OTHERMASK" kicad
 
 When printed, the debug will be prefixed with a timestamp and the trace mask:
 
-    11:22:33: Trace: (KICAD_FIND_ITEM)   item Symbol GNDPWR, #PWR020
+    11:22:33: Trace: (TRACEMASK) My trace, value: 42
+
+If you add a trace mask, define and document the mask as a variable in
+`include/trace_helpers.h`. This will add it to the [trace mask documentation][].
 
 Some available masks:
 
@@ -260,4 +263,5 @@ Some available masks:
 [CTest]: https://cmake.org/cmake/help/latest/module/CTest.html
 [Boost Unit Test framework]: https://www.boost.org/doc/libs/1_68_0/libs/test/doc/html/index.html
 [boost-test-functions]: https://www.boost.org/doc/libs/1_68_0/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref.html
-[AFL fuzzing tool]: http://lcamtuf.coredump.cx/afl/
\ No newline at end of file
+[AFL fuzzing tool]: http://lcamtuf.coredump.cx/afl/
+[trace mask documentation]: http://docs.kicad-pcb.org/doxygen/group__trace__env__vars.html
\ No newline at end of file
diff --git a/include/trace_helpers.h b/include/trace_helpers.h
index 050ab1daf..06c50f086 100644
--- a/include/trace_helpers.h
+++ b/include/trace_helpers.h
@@ -49,72 +49,100 @@
 
 /**
  * Flag to enable find debug tracing.
+ *
+ * Use "KICAD_FIND_ITEM" to enable.
  */
 extern const wxChar* const traceFindItem;
 
 /**
  * Flag to enable find and replace debug tracing.
+ *
+ * Use "KICAD_FIND_REPLACE" to enable.
  */
 extern const wxChar* const traceFindReplace;
 
 /**
  * Flag to enable draw panel coordinate debug tracing.
+ *
+ * Use "KICAD_COORDS" to enable.
  */
 extern const wxChar* const kicadTraceCoords;
 
 /**
  * Flag to enable wxKeyEvent debug tracing.
+ *
+ * Use "KICAD_KEY_EVENTS" to enable.
  */
 extern const wxChar* const kicadTraceKeyEvent;
 
 /**
  * Flag to enable auto save feature debug tracing.
+ *
+ * Use "KICAD_AUTOSAVE" to enable.
  */
 extern const wxChar* const traceAutoSave;
 
 /**
  * Flag to enable schematic library memory deletion debug output.
+ *
+ * Use "KICAD_SCH_LIB_MEM" to enable.
  */
 extern const wxChar* const traceSchLibMem;
 
 /**
  * Flag to enable legacy schematic plugin debug output.
+ *
+ * Use "KICAD_SCH_LEGACY_PLUGIN" to enable.
  */
 extern const wxChar* const traceSchLegacyPlugin;
 
 /**
  * Flag to enable GEDA PCB plugin debug output.
+ *
+ * Use "KICAD_PCB_PLUGIN" to enable.
  */
 extern const wxChar* const traceKicadPcbPlugin;
 
 /**
  * Flag to enable GEDA PCB plugin debug output.
+ *
+ * Use "KICAD_GEDA_PLUGIN" to enable.
  */
 extern const wxChar* const traceGedaPcbPlugin;
 
 /**
  * Flag to enable print controller debug output.
+ *
+ * Use "KICAD_PRINT" to enable.
  */
 extern const wxChar* const tracePrinting;
 
 /**
  * Flag to enable path and file name debug output.
+ *
+ * Use "KICAD_PATHS_AND_FILES" to enable.
  */
 extern const wxChar* const tracePathsAndFiles;
 
 /**
  * Flag to enable locale debug output.
+ *
+ * Use "KICAD_LOCALE" to enable.
  */
 extern const wxChar* const traceLocale;
 
 /**
  * Flag to enable debug output of #BASE_SCREEN and it's derivatives.
+ *
+ * Use "KICAD_SCREEN" to enable.
  */
 extern const wxChar* const traceScreen;
 
 /**
  * Flag to enable debug output of zoom-scrolling calculations in
- * #KIGFX::ZOOM_CONTROLER and derivatives.
+ * #KIGFX::ZOOM_CONTROLLER and derivatives.
+ *
+ * Use "KICAD_ZOOM_SCROLL" to enable.
  */
 extern const wxChar* const traceZoomScroll;
 
-- 
2.19.2