Support for anonymous structures, unions and enumerators is tricky due
to the versatility of the C syntax. The updated examples should
illustrate and document typical scenarios as well as provide a
justification for the chosen approach.
---
test/example-40-enum.c | 17 ++++++++++++++
test/example-50-struct.c | 28 +++++++++++++++++++++++
test/example-50-struct.stdout | 42 +++++++++++++++++++++++++++++++++++
3 files changed, 87 insertions(+)
diff --git a/test/example-40-enum.c b/test/example-40-enum.c
index e1431df..09df14d 100644
--- a/test/example-40-enum.c
+++ b/test/example-40-enum.c
@@ -11,3 +11,20 @@ enum mode {
*/
MODE_SECONDARY,
};
+
+/*
+ * Unlike structures or unions, when it comes to anonymous enumerations, you
may
+ * want to do this. Documentation will not be issued for the members though.
+ *
+ * Doing so would be tricky, and a single approach was chosen to unify
+ * structures, unions and enumerators instead. See `instance` and `struct_type`
+ * in the structures examples' section for alternatives that do emit the
+ * documentation below.
+ */
+enum {
+ /** Safe for work. */
+ SFW,
+
+ /** You know this one. */
+ NSFW,
+};
diff --git a/test/example-50-struct.c b/test/example-50-struct.c
index 550f113..f468dfb 100644
--- a/test/example-50-struct.c
+++ b/test/example-50-struct.c
@@ -8,3 +8,31 @@ struct list {
/** Data. */
list_data_t data;
};
+
+/**
+ * Anonymous structure. Type documentation gets assigned to the instance
+ * instead. This is typically the desired outcome. Same rules apply to unions
+ * and enumerations.
+ *
+ * Note that all instances receive this documentation.
+ */
+struct {
+ /** Member. Listed in the scope of the last instantiated variable. */
+ int member;
+} /** Ignored if present. */ instance1, instance2;
+
+/**
+ * Instantiated structure. This is the type documentation. Same rules apply to
+ * unions and enumerations.
+ */
+struct struct_type {
+ /** Member. Listed in the type scope. */
+ int member;
+}
+/**
+ * This is the 1st instance documentation. This is arguably ugly (in the source
+ * code), so you should split the instantiation from the type declaration. As a
+ * rule, do not try to document condensed code like this: it's less readable
and
+ * it's ambiguous as to what the documentation refers to.
+ */
+instance, undocumented_instance;
diff --git a/test/example-50-struct.stdout b/test/example-50-struct.stdout
index 2eff861..2ad58ba 100644
--- a/test/example-50-struct.stdout
+++ b/test/example-50-struct.stdout
@@ -13,3 +13,45 @@
Data.
+
+.. c:var:: struct <anonymous> instance1
+
+ Anonymous structure. Type documentation gets assigned to the instance
+ instead. This is typically the desired outcome. Same rules apply to unions
+ and enumerations.
+
+ Note that all instances receive this documentation.
+
+
+.. c:var:: struct <anonymous> instance2
+
+ Anonymous structure. Type documentation gets assigned to the instance
+ instead. This is typically the desired outcome. Same rules apply to unions
+ and enumerations.
+
+ Note that all instances receive this documentation.
+
+
+ .. c:member:: int member
+
+ Member. Listed in the scope of the last instantiated variable.
+
+
+.. c:type:: struct struct_type
+
+ Instantiated structure. This is the type documentation. Same rules apply to
+ unions and enumerations.
+
+
+ .. c:member:: int member
+
+ Member. Listed in the type scope.
+
+
+.. c:var:: struct struct_type instance
+
+ This is the 1st instance documentation. This is arguably ugly (in the source
+ code), so you should split the instantiation from the type declaration. As a
+ rule, do not try to document condensed code like this: it's less readable
and
+ it's ambiguous as to what the documentation refers to.
+
--
2.20.1
