1

let's imagine we have a C++ project that should work on several platforms (for example, arm/arm64) and we need to have target-specific values for each of them.

Right now we do:

#ifdef PLATFORM_ARM
#define TIMEOUT_VALUE 0
#define OUR_MAGIC_VALUE 1
#elif PLATFORM_ARM64
#define TIMEOUT_VALUE 2
#define OUR_MAGIC_VALUE 3
#endif

where could I place a comment for each defined name that it could be accessed from each definition?

Note: I can't define each value in its own #ifdef like 

// a comment for TIMEOUT_VALUE
#ifdef PLATFORM_ARM
#define TIMEOUT_VALUE 0
#elif PLATFORM_ARM64
#define TIMEOUT_VALUE 2
#endif 

// a comment for OUR_MAGIC_VALUE
#ifdef PLATFORM_ARM
#define OUR_MAGIC_VALUE 1
#elif PLATFORM_ARM64
#define OUR_MAGIC_VALUE 2
#endif

because I have lists and trees of such values.

Thank you.

Edit 1: for example, we have 6 targets and 4 of them support a FEATURE, so we write:

#if defined(ARM)
#define FEATURE 1
#elif defined(ARM64)
#define FEATURE 0
#elif define(MIPS)
#define FEATURE 1
etc... for other platforms.

then I have code that reads this define somewhere:

#if FEATURE
     do something. Note that this part can't be described in a target specific file, because it can have the same implementation for several targets.
#endif

and now I want to have a place to describe in general what this FEATURE means and do.

AC-93
  • 85
  • 1
  • 7
  • I don't get what this is about. You want comments controlled by conditional compilation? How do you access a comment from a definition? Comments are one of the first casualties of compilation. They cease to exist. – user4581301 Nov 07 '18 at 06:24
  • 2
    Side note. Rather than conditional compilation, I separate the different targets out into into separate source files and let what gets compiled and linked be sorted out by the build system. – user4581301 Nov 07 '18 at 06:26
  • Second vote for separate source files. Then, you can have a "example" version of the header, and put documentation there. – o11c Nov 07 '18 at 06:27
  • 2
    @user4581301 Conditional comments - sounds funny. Though, considering that this sources may also be subject of a doc. tool (like e.g. Doxygen), this could make sense somehow. (AFAIK, Doxygen can evaluate conditions as well but I'm not sure - haven't used this myself until now.) – Scheff's Cat Nov 07 '18 at 06:28
  • 2
    @user4581301 Concerning Doxygen, I was right: [Doxygen - Preprocessing](https://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html). – Scheff's Cat Nov 07 '18 at 06:30
  • +1 for Scheff, not that comments are worth much past bragging rights. Wasn't thinking document generation. – user4581301 Nov 07 '18 at 06:30
  • This idea with doc. tool was hypothetical - the only thing where I could imagine that your requirement makes sense. Can you confirm that this is your intention? If so, what doc. tool do you intend to use? (Concerning Doxygen, definitions and doc. may be separated: [Doxygen - Documentation at other places](https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#structuralcommands).) – Scheff's Cat Nov 07 '18 at 06:36

1 Answers1

4

You can define a proxy macro and write a single comment for macro to be used by end user:

#ifdef PLATFORM_ARM
#define TIMEOUT_VALUE_IMPL 0
#define OUR_MAGIC_VALUE_IMPL 1
#elif PLATFORM_ARM64
#define TIMEOUT_VALUE_IMPL 2
#define OUR_MAGIC_VALUE_IMPL 3
#endif 

// a comment for TIMEOUT_VALUE
#define TIMEOUT_VALUE TIMEOUT_VALUE_IMPL

// a comment for OUR_MAGIC_VALUE
#define OUR_MAGIC_VALUE OUR_MAGIC_VALUE_IMPL

You may also consider using constants instead of macros.

user7860670
  • 35,849
  • 4
  • 58
  • 84
  • Looks great, thank you, thinking about downsides and can't find anything big. Maybe I would add #undef TIMEOUT_VALUE_IMPL to guarantee that nobody else will use IMPL. – AC-93 Nov 07 '18 at 07:01
  • @SergeyAndreenko Be aware that macros are resolved only when actually used. So you even can first `#define XYZ XYZ_IMPL` and define the implementations *below*. So the comments would catch the user right at top of the file. – Aconcagua Nov 07 '18 at 07:35
  • @Aconcagua However defining `#define XYZ XYZ_IMPL` prior to `#define XYZ_IMPL` may prevent intellisense and other syntax tools from figuring out substitution value. – user7860670 Nov 07 '18 at 07:46
  • @Aconcagua thank you. I am planning to define *_IMPL in target specific files (like targetArm.h, targetx86 etc) and combine them in another file with all comments. – AC-93 Nov 07 '18 at 08:15