Merge pull request #1485 from AndrejMitrovic/Fix648_2

Issue 648 - Document template mixin instantiations.
dlang · Mar 12, 2014 · fe5b9c1 · fe5b9c1
2 parents a707998 + 18ef6ab
commit fe5b9c1
Show file tree

Hide file tree

Showing 3 changed files with 237 additions and 0 deletions.
diff --git a/src/doc.c b/src/doc.c
@@ -626,6 +626,26 @@ void emitDitto(Dsymbol *s, Scope *sc)
         emitUnittestComment(sc, p, sc->lastoffset2);
 }
 
+/** Recursively expand template mixin member docs into the scope. */
+static void expandTemplateMixinComments(TemplateMixin *tm, Scope *sc)
+{
+    if (!tm->semanticRun) tm->semantic(sc);
+    TemplateDeclaration *td = (tm && tm->tempdecl) ?
+        tm->tempdecl->isTemplateDeclaration() : NULL;
+    if (td && td->members)
+    {
+        for (size_t i = 0; i < td->members->dim; i++)
+        {
+            Dsymbol *sm = (*td->members)[i];
+            TemplateMixin *tmc = sm->isTemplateMixin();
+            if (tmc && tmc->comment)
+                expandTemplateMixinComments(tmc, sc);
+            else
+                emitComment(sm, sc);
+        }
+    }
+}
+
 void emitMemberComments(ScopeDsymbol *sds, Scope *sc)
 {
     //printf("ScopeDsymbol::emitMemberComments() %s\n", toChars());
@@ -653,6 +673,10 @@ void emitMemberComments(ScopeDsymbol *sds, Scope *sc)
         {
             Dsymbol *s = (*sds->members)[i];
             //printf("\ts = '%s'\n", s->toChars());
+
+            // only expand if parent is a non-template (semantic won't work)
+            if (s->comment && s->isTemplateMixin() && s->parent && !s->parent->isTemplateDeclaration())
+                expandTemplateMixinComments((TemplateMixin *)s, sc);
             emitComment(s, sc);
         }
         sc->pop();

diff --git a/test/compilable/ddoc648.d b/test/compilable/ddoc648.d
@@ -0,0 +1,90 @@
+// PERMUTE_ARGS:
+// REQUIRED_ARGS: -D -Dd${RESULTS_DIR}/compilable -o-
+// POST_SCRIPT: compilable/extra-files/ddocAny-postscript.sh 648
+
+module ddoc648;
+
+/// Mixin declaration
+mixin template Mixin1()
+{
+    /// struct S
+    struct S { }
+}
+
+/// class A
+class A
+{
+    /// field x
+    int x;
+
+    /// no docs for mixin statement (only for expanded members)
+    mixin Mixin1!();
+}
+
+/// class AB
+class AB
+{
+    /// field x
+    int x;
+
+    // no docs for mixin or its contents, must be a ddoc comment
+    mixin Mixin1!();
+}
+
+/// Mixin declaration2
+mixin template Mixin2()
+{
+    /// struct S2
+    struct S2 { }
+}
+
+/// Mixin declaration3
+mixin template Mixin3()
+{
+    /// another field
+    int f;
+
+    /// no docs for mixin statement (only for expanded members)
+    mixin Mixin2!();
+}
+
+/// class B1
+class B1
+{
+    /// no docs for mixin statement (only for expanded members)
+    mixin Mixin3!();
+}
+
+
+/// Mixin declaration3
+mixin template Mixin4()
+{
+    /// another field
+    int f;
+
+    // no docs at all for non-ddoc comment
+    mixin Mixin2!();
+}
+
+/// class B2
+class B2
+{
+    /// no docs for mixin statement (only for expanded members)
+    mixin Mixin4!();
+}
+
+/// no docs for mixin statement (only for expanded members)
+mixin Mixin3!();
+
+///
+struct TS(T)
+{
+    mixin template MT()
+    {
+    }
+
+    mixin MT;  /// avoid calling semantic
+
+    ///
+    int field;
+}
diff --git a/test/compilable/extra-files/ddoc648.html b/test/compilable/extra-files/ddoc648.html
@@ -0,0 +1,123 @@
+<html><head>
+        <META http-equiv="content-type" content="text/html; charset=utf-8">
+        <title>ddoc648</title>
+        </head><body>
+        <h1>ddoc648</h1>
+<br><br>
+<dl><dt><big><a name="Mixin1"></a>template <u>Mixin1</u>()</big></dt>
+<dd>Mixin declaration<br><br>
+
+<dl><dt><big><a name="S"></a>struct <u>S</u>;
+</big></dt>
+<dd>struct <u>S</u><br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="A"></a>class <u>A</u>;
+</big></dt>
+<dd>class <u>A</u><br><br>
+
+<dl><dt><big><a name="A.x"></a>int <u>x</u>;
+</big></dt>
+<dd>field <u>x</u><br><br>
+
+</dd>
+<dt><big><a name="S"></a>struct <u>S</u>;
+</big></dt>
+<dd>struct <u>S</u><br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="AB"></a>class <u>AB</u>;
+</big></dt>
+<dd>class <u>AB</u><br><br>
+
+<dl><dt><big><a name="AB.x"></a>int <u>x</u>;
+</big></dt>
+<dd>field <u>x</u><br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="Mixin2"></a>template <u>Mixin2</u>()</big></dt>
+<dd>Mixin declaration2<br><br>
+
+<dl><dt><big><a name="S2"></a>struct <u>S2</u>;
+</big></dt>
+<dd>struct <u>S2</u><br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="Mixin3"></a>template <u>Mixin3</u>()</big></dt>
+<dd>Mixin declaration3<br><br>
+
+<dl><dt><big><a name="f"></a>int <u>f</u>;
+</big></dt>
+<dd>another field<br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="B1"></a>class <u>B1</u>;
+</big></dt>
+<dd>class <u>B1</u><br><br>
+
+<dl><dt><big><a name="f"></a>int <u>f</u>;
+</big></dt>
+<dd>another field<br><br>
+
+</dd>
+<dt><big><a name="S2"></a>struct <u>S2</u>;
+</big></dt>
+<dd>struct <u>S2</u><br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="Mixin4"></a>template <u>Mixin4</u>()</big></dt>
+<dd>Mixin declaration3<br><br>
+
+<dl><dt><big><a name="f"></a>int <u>f</u>;
+</big></dt>
+<dd>another field<br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="B2"></a>class <u>B2</u>;
+</big></dt>
+<dd>class <u>B2</u><br><br>
+
+<dl><dt><big><a name="f"></a>int <u>f</u>;
+</big></dt>
+<dd>another field<br><br>
+
+</dd>
+</dl>
+</dd>
+<dt><big><a name="f"></a>int <u>f</u>;
+</big></dt>
+<dd>another field<br><br>
+
+</dd>
+<dt><big><a name="S2"></a>struct <u>S2</u>;
+</big></dt>
+<dd>struct <u>S2</u><br><br>
+
+</dd>
+<dt><big><a name="TS"></a>struct <u>TS</u>(T);
+</big></dt>
+<dd><br><br>
+<dl><dt><big><a name="field"></a>int <u>field</u>;
+</big></dt>
+<dd><br><br>
+</dd>
+</dl>
+</dd>
+</dl>
+
+        <hr><small>Page generated by <a href="http://dlang.org/ddoc.html">Ddoc</a>. </small>
+        </body></html>