Make it possible to hide away parts of code in compiled snippets / symbol definitions

[mosra]

cppreference.com has some definitions marked as /* implementation defined */ (for example NAN). An equivalent functionality would be useful to have here:

• to hide away complex type definitions or default template parameters (especially when type traits and SFINAE is involved), yet still notify the user that there's some such parameter/definition instead of hiding it away completely
• to have code snippets compilable (verifying their validity) but still succint enough (e.g. hiding away variable initializers, function definitions that the compiler requires, ...)

I think this could be done with a set of macros:

• [x] MCSS_ELLIPSIS(...) / MCSS_IGNORE(...), in code snippets, would again compile to __VA_ARGS__, but will be replaced with the Unicode ellipsis character / noting when doing code highlighting for the docs (again, with a distinct color) -- possible to implement on user side since 0c5ba9a93f27023f76c2766fefdd829a8398d0d9 (and used this way in magnum, see https://github.com/mosra/m.css/issues/188#issuecomment-1003824524 for details), not a builtin feature since the snippet files themselves would need to #define that for the compiler
  • [ ] figure out a way how to make this builtin (provide a header with such definitions so the user can just #include <mcss.h>? feels a bit too tied to the doc generator), or maybe just document that the user has to #define these and then the tool will directly recognize this? or maybe provide a way to tell the tool which macro is an ellipsis and which an ignore instead
• [ ] MCSS_IMPLEMENTATION_DEFINED(...), in symbol definitions, would normally compile to __VA_ARGS__, but will be replaced with an /* implementation defined */ comment when generating docs (and the comment would be possibly styled differently from other comments -- red color?
  • [ ] same as above, provide a way to tell the tool which (user-defined) macro name should be treated like this
• [x] This would be useful for the m.code Pelican plugin as well, in case the code is used both in an article and as a source for an executable. -- done in a2460403

[marzer]

Oh, fun! I implemented pretty much exactly this in poxy without realizing you had this on the roadmap. Thought you might like a bit of an 'implementation experience' summary to serve as an example (or even just to see how it actually looks to help you make decisions re styling).

I went the magic macro route:

• Users put POXY_IMPLEMENTATION_DETAIL() in their code around features they want to hide
• Doxygen replaces that with just POXY_IMPLEMENTATION_DETAIL_IMPL (i.e. as if #define POXY_IMPLEMENTATION_DETAIL(...) POXY_IMPLEMENTATION_DETAIL_IMPL)
• Poxy's HTML post-process replaces all instances POXY_IMPLEMENTATION_DETAIL_IMPL with a C-style block comment /* ... */

Which looks like this: example

It'd be relatively simple to extend that approach to allow for user-defined macros and such. You'd obviously have much more power to do fun stuff here as part of the html generation step, rather than my kludgy post-process.

figure out a way how to make this builtin (provide a header with such definitions so the user can just #include <mcss.h>?

My relatively dumb way of solving this problem is to drag this snippet from project to project:

#if !defined(__POXY__) && !defined(POXY_IMPLEMENTATION_DETAIL)
	#define POXY_IMPLEMENTATION_DETAIL(...) __VA_ARGS__
#endif

Which doesn't require a separate header, of course, but is still invasive all the same. I guess the overhead is realtively low for any project with a single central preprocessor.h, or core.h or similar (which most will have), so either solution is going to be fine for most.