← Back to team overview

kicad-developers team mailing list archive

Re: Trace variables documentation

 

On 11/26/2018 7:02 AM, John Beard wrote:
> Hi,
> 
> Having just found the trace_helpers header (which I totally missed
> when making a list of the trace strings...), I have a couple of ideas.

I was the person who started adding them in a common file a few months
back.  I did it so I didn't have to grep the entire source tree to find
the trace string.

> 
> First: is there milage to add the strings to the trace variable docs?
> This means you can easily see what you should be writing in WXTRACE
> without having to dig into the .cpp source docs. Generally, the
> implicit rule is "Add KICAD_, camel->upper-with-underscore", but not
> always (AutoSave -> AUTOSAVE).

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 must have missed a definition of AUTOSAVE in the source.  This should
be changed to KICAD_AUTOSAVE since there is already a definition for
that in trace_helpers.h/cpp.

> 
> Second: it is possible to define a variable in other places and have
> it added to the trace_env_vars group. For example, in a .cpp:
> 
> /** \addtogroup trace_env_vars
>  *  @{
>  */
> 
> /**
>  * Enable debug for
>  */
> static const wxChar* const traceLocal = wxT( "KICAD_TRACE_LOCAL" );
> 
> /** @}*/
> 
> Perhaps not collecting all the trace variables unnecessarily in one
> header might avoid creating a(nother) header that involves very big
> recompilations for minor changes (e.g. base_frame.h and bitmaps.h).
> There are only a few now, but if we get a more comprehensive or
> granular set of trace variables, this header could become quite
> spidery.

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.

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

> 
> Using the doxygen group would allow documentation to be collated
> without introducing code-level dependencies. Very many trace variables
> will only be used in a single file. If a trace var is shared, then a
> common header may be appropriate.

The trace_helper files should be used when a trace string is used in
more than one source file.

> 
> Cheers,
> 
> John
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~kicad-developers
> Post to     : kicad-developers@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~kicad-developers
> More help   : https://help.launchpad.net/ListHelp
> 


Follow ups

References