Merge pull request #4338 from quickfur/ddoc_para

Issue 9731: implement $(DDOC_PARAGRAPH)
dlang · Jan 26, 2015 · 0f97ab5 · 0f97ab5
2 parents 0fd5758 + 34467ee
commit 0f97ab5
Show file tree

Hide file tree

Showing 3 changed files with 157 additions and 1 deletion.
diff --git a/src/doc.c b/src/doc.c
@@ -224,6 +224,7 @@ DDOC_PARAM_ROW = $(TR $0)\n\
 DDOC_PARAM_ID  = $(TD $0)\n\
 DDOC_PARAM_DESC = $(TD $0)\n\
 DDOC_BLANKLINE  = $(BR)$(BR)\n\
+DDOC_PARAGRAPH  = $0\n\
 \n\
 DDOC_ANCHOR     = <a name=\"$1\"></a>\n\
 DDOC_PSYMBOL    = $(U $0)\n\
@@ -2211,6 +2212,7 @@ void highlightText(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
     int leadingBlank = 1;
     int inCode = 0;
     int inBacktick = 0;
+    int inParagraph = 0;
     //int inComment = 0;                  // in <!-- ... --> comment
     size_t iCodeStart = 0;                    // start of code section
     size_t codeIndent = 0;
@@ -2247,8 +2249,14 @@ void highlightText(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
                 if (!sc->module->isDocFile &&
                     !inCode && i == iLineStart && i + 1 < buf->offset)    // if "\n\n"
                 {
-                    static const char blankline[] = "$(DDOC_BLANKLINE)\n";
+                    if (inParagraph)
+                    {
+                        static const char endpara[] = ")";
+                        i = buf->insert(i, endpara, strlen(endpara));
+                        inParagraph = 0;
+                    }
 
+                    static const char blankline[] = "$(DDOC_BLANKLINE)\n";
                     i = buf->insert(i, blankline, strlen(blankline));
                 }
                 leadingBlank = 1;
@@ -2478,6 +2486,15 @@ void highlightText(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
                         static const char d_code[] = "$(D_CODE ";
 
                         inCode = 1;
+
+                        // Code blocks end any paragraphs in progress.
+                        if (inParagraph)
+                        {
+                            static const char endpara[] = ")";
+                            i = buf->insert(i, endpara, strlen(endpara));
+                            inParagraph = 0;
+                        }
+
                         codeIndent = istart - iLineStart;  // save indent count
                         i = buf->insert(i, d_code, strlen(d_code));
                         iCodeStart = i;
@@ -2489,6 +2506,14 @@ void highlightText(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
 
             default:
                 leadingBlank = 0;
+
+                if (!inCode && !inParagraph)
+                {
+                    static const char para[] = "$(DDOC_PARAGRAPH ";
+                    i = buf->insert(i, para, strlen(para)) - 1;
+                    inParagraph = 1;
+                }
+
                 if (!sc->module->isDocFile &&
                     !inCode && isIdStart((utf8_t *)&buf->data[i]))
                 {
@@ -2541,6 +2566,10 @@ void highlightText(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
     if (inCode)
         s->error("unmatched --- in DDoc comment");
     ;
+    if (inParagraph)
+    {
+        buf->writestring(")");
+    }
 }
 
 /**************************************************

diff --git a/test/compilable/ddocparagraph.d b/test/compilable/ddocparagraph.d
@@ -0,0 +1,58 @@
+// PERMUTE_ARGS:
+// REQUIRED_ARGS: -D -Dd${RESULTS_DIR}/compilable -o-
+// POST_SCRIPT: compilable/extra-files/ddocAny-postscript.sh paragraph
+
+/**
+ * $(DDOC_COMMENT Note: The use of a nonexistent <paragraph> tag is deliberate,
+ * to make sure it comes from the expansion of DDOC_PARAGRAPH and not from
+ * something else that happens to also use <p>.)
+ *
+ * Macros:
+ * BR=<break>
+ * DDOC_PARAGRAPH=<paragraph>$0</paragraph>
+ */
+module ddocparagraph;
+
+/**
+ * Function summary goes here. Should be in own paragraph outside any section.
+ *
+ * Function description goes here. Treated as first paragraph by ddoc.
+ *
+ * Another paragraph in function description.
+ * Continues same paragraph. Should be within the same &lt;paragraph&gt; tag.
+ *
+ * Params:
+ *  x = Parameter description with multiple paragraphs.
+ *
+ *      Second paragraph here.
+ *  y = Parameter description in one paragraph.
+ *
+ * Section:
+ * Single paragraph within section.
+ *
+ * Blank_section_should_have_no_paragraph_tags:
+ *
+ * Section_with_multiple_paragraphs:
+ * First paragraph.
+ *
+ * Another paragraph.
+ *
+ * $(B Third) paragraph that starts with a macro.
+ *
+ *
+ *
+ *
+ * Blank lines before this should have no extraneous paragraph tags.
+ * ---
+ * // Code blocks end any paragraphs in progress.
+ *
+ * exampleCode(2, 1); // interspersed blank line
+ * ---
+ * Paragraph following code block without blank line.
+ *
+ * ---
+ * // Code block following blank line.
+ * ---
+ * Paragraph following code block without blank line.
+ */
+void exampleCode(int x, int y) { }
diff --git a/test/compilable/extra-files/ddocparagraph.html b/test/compilable/extra-files/ddocparagraph.html
@@ -0,0 +1,69 @@
+<html><head>
+        <META http-equiv="content-type" content="text/html; charset=utf-8">
+        <title>ddocparagraph</title>
+        </head><body>
+        <h1>ddocparagraph</h1>
+<paragraph><!-- Note: The use of a nonexistent <paragraph> tag is deliberate,
+ to make sure it comes from the expansion of DDOC_PARAGRAPH and not from
+ something else that happens to also use <p>. -->
+</paragraph><break><break>
+
+<dl><dt><big><a name="exampleCode"></a>void <u>exampleCode</u>(int <i>x</i>, int <i>y</i>);
+</big></dt>
+<dd><paragraph>Function summary goes here. Should be in own paragraph outside any section.
+</paragraph><break><break>
+<paragraph>Function description goes here. Treated as first paragraph by ddoc.
+</paragraph><break><break>
+
+ <paragraph>Another paragraph in function description.
+ Continues same paragraph. Should be within the same &lt;paragraph&gt; tag.
+
+</paragraph><break><break>
+<b>Params:</b><break>
+<table><tr><td>int <i>x</i></td>
+<td><paragraph>Parameter description with multiple paragraphs.
+</paragraph><break><break>
+
+      <paragraph>Second paragraph here.</paragraph></td></tr>
+<tr><td>int <i>y</i></td>
+<td><paragraph>Parameter description in one paragraph.</paragraph></td></tr>
+</table><break>
+<b>Section:</b><break>
+<paragraph>Single paragraph within section.
+
+</paragraph><break><break>
+<b>Blank section should have no paragraph tags:</b><break>
+<break><break>
+<b>Section with multiple paragraphs:</b><break>
+ <paragraph>First paragraph.
+</paragraph><break><break>
+
+ <paragraph>Another paragraph.
+</paragraph><break><break>
+
+ <paragraph><b>Third</b> paragraph that starts with a macro.
+</paragraph><break><break>
+
+<break><break>
+
+<break><break>
+
+<break><break>
+
+ <paragraph>Blank lines before this should have no extraneous paragraph tags.
+</paragraph><pre class="d_code"><font color=green>// Code blocks end any paragraphs in progress.
+</font>
+<u>exampleCode</u>(2, 1); <font color=green>// interspersed blank line
+</font></pre>
+ <paragraph>Paragraph following code block without blank line.
+</paragraph><break><break>
+
+<pre class="d_code"><font color=green>// Code block following blank line.
+</font></pre>
+ <paragraph>Paragraph following code block without blank line.</paragraph><break><break>
+
+</dd>
+</dl>
+
+        <hr><small>Page generated by <a href="http://dlang.org/ddoc.html">Ddoc</a>. </small>
+        </body></html>