[#MRDOCS_DESCRIBE_ENUM_BEGIN]
= MRDOCS_DESCRIBE_ENUM_BEGIN
:mrdocs:

Open an enum description driven by an X‐macro `.inc` file.

== Synopsis

Declared in `<mrdocs/Support/Reflection/Describe.hpp>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
#define MRDOCS_DESCRIBE_ENUM_BEGIN(E)

----

== Description

Use it when the enumerators already live in an X‐macro `.inc` file, one `INFO(Name)` line per enumerator, that also defines the enum. You then describe the enum from the same list instead of repeating every name in `MRDOCS_DESCRIBE_ENUM`, so the two can't drift apart.

Given this `ShapeNodes.inc`:

[,cpp]
----
#ifndef INFO
#define INFO(Name)
#endif

INFO(Circle)
INFO(RoundedRect)
INFO(Triangle)

#undef INFO
----
include it once to define the enum and once more between `MRDOCS_DESCRIBE_ENUM_BEGIN` and `MRDOCS_DESCRIBE_ENUM_END`, with `INFO` pointed at `MRDOCS_ENUM_ENTRY`:

[,cpp]
----
namespace shapes {

enum class ShapeKind
{
    None = 0,
#define INFO(Name) Name,
#include "ShapeNodes.inc"
};

MRDOCS_DESCRIBE_ENUM_BEGIN(ShapeKind)
#define INFO(Name) MRDOCS_ENUM_ENTRY(ShapeKind, Name)
#include "ShapeNodes.inc"
MRDOCS_DESCRIBE_ENUM_END(ShapeKind)

} // namespace shapes
----
The `.inc` file `#undef`s `INFO` itself, so no cleanup line is needed. The three pieces together produce the same declaration as `MRDOCS_DESCRIBE_ENUM(ShapeKind, Circle, RoundedRect, Triangle)`:

[,cpp]
----
// Simplified: each lambda is a distinct closure type that returns the
// stringized name.

// MRDOCS_DESCRIBE_ENUM_BEGIN(ShapeKind)
static_assert(std::is_enum_v<ShapeKind>,
    "MRDOCS_DESCRIBE_ENUM should only be used with enums");
[[maybe_unused]]
decltype(::mrdocs::describe::detail::enum_descriptor_fn_impl(0

// #include "ShapeNodes.inc": one MRDOCS_ENUM_ENTRY per INFO line
    , ::mrdocs::describe::detail::enum_descriptor<
        ShapeKind::Circle, []{ return "Circle"; }>{}
    , ::mrdocs::describe::detail::enum_descriptor<
        ShapeKind::RoundedRect, []{ return "RoundedRect"; }>{}
    , ::mrdocs::describe::detail::enum_descriptor<
        ShapeKind::Triangle, []{ return "Triangle"; }>{}

// MRDOCS_DESCRIBE_ENUM_END(ShapeKind)
)) mrdocs_enum_descriptor_fn(ShapeKind**);
----
Here `None` isn&apos;t in the `&period;inc` file, so it isn&apos;t described&colon; `toString(ShapeKind&colon;&colon;None)` is empty, while `toString(ShapeKind&colon;&colon;RoundedRect)` is `&quot;rounded&hyphen;rect&quot;`&period;

Things to keep in mind&colon;

* The macro opens a parenthesized expression that `MRDOCS&lowbar;DESCRIBE&lowbar;ENUM&lowbar;END` closes, so everything in between must expand to nothing but `MRDOCS&lowbar;ENUM&lowbar;ENTRY` calls (and preprocessor directives)&period; Each entry starts with its own comma, so don&apos;t add separators&period;
* Pass the same enum type to both macros&period;
* The placement rules of `MRDOCS&lowbar;DESCRIBE&lowbar;ENUM` apply&colon; namespace scope, in the namespace of the enum, never inside a class&period;
* Don&apos;t put a `&semi;` after either macro&period; After this one it&apos;s a syntax error, and `MRDOCS&lowbar;DESCRIBE&lowbar;ENUM&lowbar;END` already ends with one&period;
* Unlike `MRDOCS&lowbar;DESCRIBE&lowbar;ENUM`, there&apos;s no limit on the number of enumerators&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *E*
| The enum type&period;
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#