[#MRDOCS_DESCRIBE_KINDS_BEGIN]
= MRDOCS_DESCRIBE_KINDS_BEGIN
:mrdocs:

Open a kinds 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_KINDS_BEGIN(C)

----

== Description

When the derived kinds already live in an X‐macro `.inc` file (one `INFO(Name)` per kind, often the same file that builds the kind enum), this registers them without repeating the list in `MRDOCS_DESCRIBE_KINDS`. Point `INFO` at `MRDOCS_KIND_ENTRY`, then bracket the include with this macro and `MRDOCS_DESCRIBE_KINDS_END`. Given this `ShapeNodes.inc`:

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

INFO(Circle)
INFO(Square)

#undef INFO
----
a header can build both the enum and the kind list from it:

[,cpp]
----
namespace shapes {

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

struct Shape { ShapeKind Kind; };

struct CircleShape : Shape
{
    static constexpr ShapeKind kind_id = ShapeKind::Circle;
    CircleShape() : Shape{kind_id} {}
};

struct SquareShape : Shape
{
    static constexpr ShapeKind kind_id = ShapeKind::Square;
    SquareShape() : Shape{kind_id} {}
};

#define INFO(Name) MRDOCS_KIND_ENTRY(Shape, Name##Shape)
MRDOCS_DESCRIBE_KINDS_BEGIN(Shape)
#include "ShapeNodes.inc"
MRDOCS_DESCRIBE_KINDS_END(Shape)

} // namespace shapes
----
The entries can also be written by hand, and an empty pair registers a base with no kinds:

[,cpp]
----
MRDOCS_DESCRIBE_KINDS_BEGIN(Node)
    MRDOCS_KIND_ENTRY(Node, Leaf)
    MRDOCS_KIND_ENTRY(Node, Branch)
MRDOCS_DESCRIBE_KINDS_END(Node)

MRDOCS_DESCRIBE_KINDS_BEGIN(Empty)
MRDOCS_DESCRIBE_KINDS_END(Empty)
----
After preprocessing, the `Shape` block becomes the following (simplified: the `::mrdocs::describe::detail::` qualification is dropped and the assertion message is shortened):

[,cpp]
----
// MRDOCS_DESCRIBE_KINDS_BEGIN(Shape): leaves the call open
static_assert(std::is_class_v<Shape>, "...");
[[maybe_unused]]
inline decltype(kind_descriptor_fn_impl(0

// #include "ShapeNodes.inc": one MRDOCS_KIND_ENTRY per INFO line
    , kind_descriptor<Shape, CircleShape>{}   // INFO(Circle)
    , kind_descriptor<Shape, SquareShape>{}   // INFO(Square)

// MRDOCS_DESCRIBE_KINDS_END(Shape): closes the call
)) mrdocs_kind_descriptor_fn(Shape**) { return {}; }
----
That&apos;s the same declaration `MRDOCS&lowbar;DESCRIBE&lowbar;KINDS(Shape, CircleShape, SquareShape)` produces, so the same queries (`describe&colon;&colon;describe&lowbar;kinds`, `describe&colon;&colon;has&lowbar;describe&lowbar;kinds`, `mrdocs&colon;&colon;visit`) work afterwards&period;

Things to keep in mind&colon;

* This macro leaves a call open, so only `MRDOCS&lowbar;KIND&lowbar;ENTRY` expansions and preprocessor directives may come before the matching `MRDOCS&lowbar;DESCRIBE&lowbar;KINDS&lowbar;END`&period; Anything else, including a stray `&semi;`, is a syntax error&period;
* Pass the same base to this macro, to every entry, and to `MRDOCS&lowbar;DESCRIBE&lowbar;KINDS&lowbar;END`&period;
* Place the block at namespace scope, in the namespace of the base&period;
* Define `INFO` before the include&period; The `&period;inc` file is expected to `&num;undef` it at the end&semi; if yours doesn&apos;t, add the `&num;undef` yourself&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *C*
| The polymorphic base class&period;
|===


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