gcc/d/dmd/doc.c - gcc - Git at Google


 /* Compiler implementation of the D programming language
  * Copyright (C) 1999-2021 by The D Language Foundation, All Rights Reserved
  * written by Walter Bright
  * http://www.digitalmars.com
  * Distributed under the Boost Software License, Version 1.0.
  * http://www.boost.org/LICENSE_1_0.txt
  * https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c
  */

 // This implements the Ddoc capability.

 #include "root/dsystem.h"
 #include "root/rmem.h"
 #include "root/root.h"
 #include "root/port.h"
 #include "root/aav.h"

 #include "attrib.h"
 #include "cond.h"
 #include "mars.h"
 #include "dsymbol.h"
 #include "macro.h"
 #include "template.h"
 #include "lexer.h"
 #include "aggregate.h"
 #include "declaration.h"
 #include "statement.h"
 #include "enum.h"
 #include "id.h"
 #include "module.h"
 #include "scope.h"
 #include "hdrgen.h"
 #include "doc.h"
 #include "mtype.h"
 #include "utf.h"

 void emitMemberComments(ScopeDsymbol *sds, OutBuffer *buf, Scope *sc);
 void toDocBuffer(Dsymbol *s, OutBuffer *buf, Scope *sc);
 void emitComment(Dsymbol *s, OutBuffer *buf, Scope *sc);

 struct Escape
 {
     const char *strings[256];

     const char *escapeChar(unsigned c);
 };

 class Section
 {
 public:
     const utf8_t *name;
     size_t namelen;

     const utf8_t *body;
     size_t bodylen;

     int nooutput;

     virtual void write(Loc loc, DocComment *dc, Scope *sc, Dsymbols *a, OutBuffer *buf);
 };

 class ParamSection : public Section
 {
 public:
     void write(Loc loc, DocComment *dc, Scope *sc, Dsymbols *a, OutBuffer *buf);
 };

 class MacroSection : public Section
 {
 public:
     void write(Loc loc, DocComment *dc, Scope *sc, Dsymbols *a, OutBuffer *buf);
 };

 typedef Array<Section *> Sections;

 struct DocComment
 {
     Sections sections;             // Section*[]

     Section *summary;
     Section *copyright;
     Section *macros;
     Macro **pmacrotable;
     Escape **pescapetable;

     Dsymbols a;

     DocComment() :
        summary(NULL), copyright(NULL), macros(NULL), pmacrotable(NULL), pescapetable(NULL)
     { }

     static DocComment *parse(Dsymbol *s, const utf8_t *comment);
     static void parseMacros(Escape **pescapetable, Macro **pmacrotable, const utf8_t *m, size_t mlen);
     static void parseEscapes(Escape **pescapetable, const utf8_t *textstart, size_t textlen);

     void parseSections(const utf8_t *comment);
     void writeSections(Scope *sc, Dsymbols *a, OutBuffer *buf);
 };


 int cmp(const char *stringz, const void *s, size_t slen);
 int icmp(const char *stringz, const void *s, size_t slen);
 bool isDitto(const utf8_t *comment);
 const utf8_t *skipwhitespace(const utf8_t *p);
 size_t skiptoident(OutBuffer *buf, size_t i);
 size_t skippastident(OutBuffer *buf, size_t i);
 size_t skippastURL(OutBuffer *buf, size_t i);
 void highlightText(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset);
 void highlightCode(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset);
 void highlightCode(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset);
 void highlightCode2(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset);
 void highlightCode3(Scope *sc, OutBuffer *buf, const utf8_t *p, const utf8_t *pend);
 TypeFunction *isTypeFunction(Dsymbol *s);
 Parameter *isFunctionParameter(Dsymbols *a, const utf8_t *p, size_t len);
 TemplateParameter *isTemplateParameter(Dsymbols *a, const utf8_t *p, size_t len);

 bool isIdStart(const utf8_t *p);
 bool isCVariadicArg(const utf8_t *p, size_t len);
 bool isIdTail(const utf8_t *p);
 bool isIndentWS(const utf8_t *p);
 int utfStride(const utf8_t *p);

 // Workaround for missing Parameter instance for variadic params. (it's unnecessary to instantiate one).
 bool isCVariadicParameter(Dsymbols *a, const utf8_t *p, size_t len)
 {
     for (size_t i = 0; i < a->length; i++)
     {
         TypeFunction *tf = isTypeFunction((*a)[i]);
         if (tf && tf->parameterList.varargs == VARARGvariadic && cmp("...", p, len) == 0)
             return true;
     }
     return false;
 }

 /****************************************************
  */
 static Parameter *isFunctionParameter(Dsymbol *s, const utf8_t *p, size_t len)
 {
     TypeFunction *tf = isTypeFunction(s);
     if (tf && tf->parameterList.parameters)
     {
         for (size_t k = 0; k < tf->parameterList.parameters->length; k++)
         {
             Parameter *fparam = (*tf->parameterList.parameters)[k];
             if (fparam->ident && cmp(fparam->ident->toChars(), p, len) == 0)
             {
                 return fparam;
             }
         }
     }
     return NULL;
 }

 static Dsymbol *getEponymousMember(TemplateDeclaration *td)
 {
     if (!td->onemember)
         return NULL;

     if (AggregateDeclaration *ad = td->onemember->isAggregateDeclaration())
         return ad;
     if (FuncDeclaration *fd = td->onemember->isFuncDeclaration())
         return fd;
     if (td->onemember->isEnumMember())
         return NULL;    // Keep backward compatibility. See compilable/ddoc9.d
     if (VarDeclaration *vd = td->onemember->isVarDeclaration())
         return td->constraint ? NULL : vd;

     return NULL;
 }

 /****************************************************
  */
 static Parameter *isEponymousFunctionParameter(Dsymbols *a, const utf8_t *p, size_t len)
 {
     for (size_t i = 0; i < a->length; i++)
     {
         TemplateDeclaration *td = (*a)[i]->isTemplateDeclaration();
         if (td && td->onemember)
         {
             /* Case 1: we refer to a template declaration inside the template

                /// ...ddoc...
                template case1(T) {
                  void case1(R)() {}
                }
              */
             td = td->onemember->isTemplateDeclaration();
         }
         if (!td)
         {
             /* Case 2: we're an alias to a template declaration

                /// ...ddoc...
                alias case2 = case1!int;
              */
             AliasDeclaration *ad = (*a)[i]->isAliasDeclaration();
             if (ad && ad->aliassym)
             {
                 td = ad->aliassym->isTemplateDeclaration();
             }
         }
         while (td)
         {
             Dsymbol *sym = getEponymousMember(td);
             if (sym)
             {
                 Parameter *fparam = isFunctionParameter(sym, p, len);
                 if (fparam)
                 {
                     return fparam;
                 }
             }
             td = td->overnext;
         }
     }
     return NULL;
 }

 static TemplateDeclaration *getEponymousParent(Dsymbol *s)
 {
     if (!s->parent)
         return NULL;
     TemplateDeclaration *td = s->parent->isTemplateDeclaration();
     return (td && getEponymousMember(td)) ? td : NULL;
 }

 static const char ddoc_default[] = "\
 DDOC =  <html><head>\n\
         <META http-equiv=\"content-type\" content=\"text/html; charset=utf-8\">\n\
         <title>$(TITLE)</title>\n\
         </head><body>\n\
         <h1>$(TITLE)</h1>\n\
         $(BODY)\n\
         <hr>$(SMALL Page generated by $(LINK2 http://dlang.org/ddoc.html, Ddoc). $(COPYRIGHT))\n\
         </body></html>\n\
 \n\
 B =     <b>$0</b>\n\
 I =     <i>$0</i>\n\
 U =     <u>$0</u>\n\
 P =     <p>$0</p>\n\
 DL =    <dl>$0</dl>\n\
 DT =    <dt>$0</dt>\n\
 DD =    <dd>$0</dd>\n\
 TABLE = <table>$0</table>\n\
 TR =    <tr>$0</tr>\n\
 TH =    <th>$0</th>\n\
 TD =    <td>$0</td>\n\
 OL =    <ol>$0</ol>\n\
 UL =    <ul>$0</ul>\n\
 LI =    <li>$0</li>\n\
 BIG =   <big>$0</big>\n\
 SMALL = <small>$0</small>\n\
 BR =    <br>\n\
 LINK =  <a href=\"$0\">$0</a>\n\
 LINK2 = <a href=\"$1\">$+</a>\n\
 LPAREN= (\n\
 RPAREN= )\n\
 BACKTICK= `\n\
 DOLLAR= $\n\
 DEPRECATED= $0\n\
 \n\
 RED =   <font color=red>$0</font>\n\
 BLUE =  <font color=blue>$0</font>\n\
 GREEN = <font color=green>$0</font>\n\
 YELLOW =<font color=yellow>$0</font>\n\
 BLACK = <font color=black>$0</font>\n\
 WHITE = <font color=white>$0</font>\n\
 \n\
 D_CODE = <pre class=\"d_code\">$0</pre>\n\
 DDOC_BACKQUOTED = $(D_INLINECODE $0)\n\
 D_INLINECODE = <pre style=\"display:inline;\" class=\"d_inline_code\">$0</pre>\n\
 D_COMMENT = $(GREEN $0)\n\
 D_STRING  = $(RED $0)\n\
 D_KEYWORD = $(BLUE $0)\n\
 D_PSYMBOL = $(U $0)\n\
 D_PARAM   = $(I $0)\n\
 \n\
 DDOC_COMMENT   = <!-- $0 -->\n\
 DDOC_DECL      = $(DT $(BIG $0))\n\
 DDOC_DECL_DD   = $(DD $0)\n\
 DDOC_DITTO     = $(BR)$0\n\
 DDOC_SECTIONS  = $0\n\
 DDOC_SUMMARY   = $0$(BR)$(BR)\n\
 DDOC_DESCRIPTION = $0$(BR)$(BR)\n\
 DDOC_AUTHORS   = $(B Authors:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_BUGS      = $(RED BUGS:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_COPYRIGHT = $(B Copyright:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_DATE      = $(B Date:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_DEPRECATED = $(RED Deprecated:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_EXAMPLES  = $(B Examples:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_HISTORY   = $(B History:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_LICENSE   = $(B License:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_RETURNS   = $(B Returns:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_SEE_ALSO  = $(B See Also:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_STANDARDS = $(B Standards:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_THROWS    = $(B Throws:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_VERSION   = $(B Version:)$(BR)\n$0$(BR)$(BR)\n\
 DDOC_SECTION_H = $(B $0)$(BR)\n\
 DDOC_SECTION   = $0$(BR)$(BR)\n\
 DDOC_MEMBERS   = $(DL $0)\n\
 DDOC_MODULE_MEMBERS = $(DDOC_MEMBERS $0)\n\
 DDOC_CLASS_MEMBERS  = $(DDOC_MEMBERS $0)\n\
 DDOC_STRUCT_MEMBERS = $(DDOC_MEMBERS $0)\n\
 DDOC_ENUM_MEMBERS   = $(DDOC_MEMBERS $0)\n\
 DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0)\n\
 DDOC_ENUM_BASETYPE = $0\n\
 DDOC_PARAMS    = $(B Params:)$(BR)\n$(TABLE $0)$(BR)\n\
 DDOC_PARAM_ROW = $(TR $0)\n\
 DDOC_PARAM_ID  = $(TD $0)\n\
 DDOC_PARAM_DESC = $(TD $0)\n\
 DDOC_BLANKLINE  = $(BR)$(BR)\n\
 \n\
 DDOC_ANCHOR     = <a name=\"$1\"></a>\n\
 DDOC_PSYMBOL    = $(U $0)\n\
 DDOC_PSUPER_SYMBOL = $(U $0)\n\
 DDOC_KEYWORD    = $(B $0)\n\
 DDOC_PARAM      = $(I $0)\n\
 \n\
 ESCAPES = /</&lt;/\n\
           />/&gt;/\n\
           /&/&amp;/\n\
 ";

 static const char ddoc_decl_s[] = "$(DDOC_DECL ";
 static const char ddoc_decl_e[] = ")\n";

 static const char ddoc_decl_dd_s[] = "$(DDOC_DECL_DD ";
 static const char ddoc_decl_dd_e[] = ")\n";


 /****************************************************
  */

 void gendocfile(Module *m)
 {
     static OutBuffer mbuf;
     static int mbuf_done;

     OutBuffer buf;

     //printf("Module::gendocfile()\n");

     if (!mbuf_done)             // if not already read the ddoc files
     {
         mbuf_done = 1;

         // Use our internal default
         mbuf.write(ddoc_default, strlen(ddoc_default));

         // Override with DDOCFILE specified in the sc.ini file
         char *p = getenv("DDOCFILE");
         if (p)
             global.params.ddocfiles.shift(p);

         // Override with the ddoc macro files from the command line
         for (size_t i = 0; i < global.params.ddocfiles.length; i++)
         {
             FileName f(global.params.ddocfiles[i]);
             File file(&f);
             readFile(m->loc, &file);
             // BUG: convert file contents to UTF-8 before use

             //printf("file: '%.*s'\n", file.len, file.buffer);
             mbuf.write(file.buffer, file.len);
         }
     }
     DocComment::parseMacros(&m->escapetable, &m->macrotable, (utf8_t *)mbuf.slice().ptr, mbuf.length());

     Scope *sc = Scope::createGlobal(m);      // create root scope

     DocComment *dc = DocComment::parse(m, m->comment);
     dc->pmacrotable = &m->macrotable;
     dc->pescapetable = &m->escapetable;
     sc->lastdc = dc;

     // Generate predefined macros

     // Set the title to be the name of the module
     {
         const char *p = m->toPrettyChars();
         Macro::define(&m->macrotable, (const utf8_t *)"TITLE", 5, (const utf8_t *)p, strlen(p));
     }

     // Set time macros
     {
         time_t t;
         time(&t);
         char *p = ctime(&t);
         p = mem.xstrdup(p);
         Macro::define(&m->macrotable, (const utf8_t *)"DATETIME", 8, (const utf8_t *)p, strlen(p));
         Macro::define(&m->macrotable, (const utf8_t *)"YEAR", 4, (const utf8_t *)p + 20, 4);
     }

     const char *srcfilename = m->srcfile->toChars();
     Macro::define(&m->macrotable, (const utf8_t *)"SRCFILENAME", 11, (const utf8_t *)srcfilename, strlen(srcfilename));

     const char *docfilename = m->docfile->toChars();
     Macro::define(&m->macrotable, (const utf8_t *)"DOCFILENAME", 11, (const utf8_t *)docfilename, strlen(docfilename));

     if (dc->copyright)
     {
         dc->copyright->nooutput = 1;
         Macro::define(&m->macrotable, (const utf8_t *)"COPYRIGHT", 9, dc->copyright->body, dc->copyright->bodylen);
     }

     buf.printf("$(DDOC_COMMENT Generated by Ddoc from %s)\n", m->srcfile->toChars());
     if (m->isDocFile)
     {
         Loc loc = m->md ? m->md->loc : m->loc;
         size_t commentlen = strlen((const char *)m->comment);
         Dsymbols a;
         // Bugzilla 9764: Don't push m in a, to prevent emphasize ddoc file name.
         if (dc->macros)
         {
             commentlen = dc->macros->name - m->comment;
             dc->macros->write(loc, dc, sc, &a, &buf);
         }
         buf.write(m->comment, commentlen);
         highlightText(sc, &a, &buf, 0);
     }
     else
     {
         Dsymbols a;
         a.push(m);
         dc->writeSections(sc, &a, &buf);
         emitMemberComments(m, &buf, sc);
     }

     //printf("BODY= '%.*s'\n", buf.length(), buf.slice().ptr);
     Macro::define(&m->macrotable, (const utf8_t *)"BODY", 4, (const utf8_t *)buf.slice().ptr, buf.length());

     OutBuffer buf2;
     buf2.writestring("$(DDOC)\n");
     size_t end = buf2.length();
     m->macrotable->expand(&buf2, 0, &end, NULL, 0);

     /* Remove all the escape sequences from buf2,
      * and make CR-LF the newline.
      */
     {
         buf.setsize(0);
         buf.reserve(buf2.length());
         utf8_t *p = (utf8_t *)buf2.slice().ptr;
         for (size_t j = 0; j < buf2.length(); j++)
         {
             utf8_t c = p[j];
             if (c == 0xFF && j + 1 < buf2.length())
             {
                 j++;
                 continue;
             }
             if (c == '\n')
                 buf.writeByte('\r');
             else if (c == '\r')
             {
                 buf.writestring("\r\n");
                 if (j + 1 < buf2.length() && p[j + 1] == '\n')
                 {
                     j++;
                 }
                 continue;
             }
             buf.writeByte(c);
         }
     }

     // Transfer image to file
     assert(m->docfile);
     m->docfile->setbuffer(buf.slice().ptr, buf.length());
     m->docfile->ref = 1;
     ensurePathToNameExists(Loc(), m->docfile->toChars());
     writeFile(m->loc, m->docfile);
 }

 /****************************************************
  * Having unmatched parentheses can hose the output of Ddoc,
  * as the macros depend on properly nested parentheses.
  * This function replaces all ( with $(LPAREN) and ) with $(RPAREN)
  * to preserve text literally. This also means macros in the
  * text won't be expanded.
  */
 void escapeDdocString(OutBuffer *buf, size_t start)
 {
     for (size_t u = start; u < buf->length(); u++)
     {
         utf8_t c = buf->slice().ptr[u];
         switch(c)
         {
             case '$':
                 buf->remove(u, 1);
                 buf->insert(u, (const char *)"$(DOLLAR)", 9);
                 u += 8;
                 break;

             case '(':
                 buf->remove(u, 1); //remove the (
                 buf->insert(u, (const char *)"$(LPAREN)", 9); //insert this instead
                 u += 8; //skip over newly inserted macro
                 break;

             case ')':
                 buf->remove(u, 1); //remove the )
                 buf->insert(u, (const char *)"$(RPAREN)", 9); //insert this instead
                 u += 8; //skip over newly inserted macro
                 break;
         }
     }
 }

 /****************************************************
  * Having unmatched parentheses can hose the output of Ddoc,
  * as the macros depend on properly nested parentheses.

  * Fix by replacing unmatched ( with $(LPAREN) and unmatched ) with $(RPAREN).
  */
 void escapeStrayParenthesis(Loc loc, OutBuffer *buf, size_t start)
 {
     unsigned par_open = 0;

     for (size_t u = start; u < buf->length(); u++)
     {
         utf8_t c = buf->slice().ptr[u];
         switch(c)
         {
             case '(':
                 par_open++;
                 break;

             case ')':
                 if (par_open == 0)
                 {
                     //stray ')'
                     warning(loc, "Ddoc: Stray ')'. This may cause incorrect Ddoc output."
                         " Use $(RPAREN) instead for unpaired right parentheses.");
                     buf->remove(u, 1); //remove the )
                     buf->insert(u, (const char *)"$(RPAREN)", 9); //insert this instead
                     u += 8; //skip over newly inserted macro
                 }
                 else
                     par_open--;
                 break;
         }
     }

     if (par_open)                       // if any unmatched lparens
     {
         par_open = 0;
         for (size_t u = buf->length(); u > start;)
         {
             u--;
             utf8_t c = buf->slice().ptr[u];
             switch(c)
             {
                 case ')':
                     par_open++;
                     break;

                 case '(':
                     if (par_open == 0)
                     {
                         //stray '('
                         warning(loc, "Ddoc: Stray '('. This may cause incorrect Ddoc output."
                             " Use $(LPAREN) instead for unpaired left parentheses.");
                         buf->remove(u, 1); //remove the (
                         buf->insert(u, (const char *)"$(LPAREN)", 9); //insert this instead
                     }
                     else
                         par_open--;
                     break;
             }
         }
     }
 }

 // Basically, this is to skip over things like private{} blocks in a struct or
 // class definition that don't add any components to the qualified name.
 static Scope *skipNonQualScopes(Scope *sc)
 {
     while (sc && !sc->scopesym)
         sc = sc->enclosing;
     return sc;
 }

 static bool emitAnchorName(OutBuffer *buf, Dsymbol *s, Scope *sc)
 {
     if (!s || s->isPackage() || s->isModule())
         return false;

     // Add parent names first
     bool dot = false;
     if (s->parent)
         dot = emitAnchorName(buf, s->parent, sc);
     else if (sc)
         dot = emitAnchorName(buf, sc->scopesym, skipNonQualScopes(sc->enclosing));

     // Eponymous template members can share the parent anchor name
     if (getEponymousParent(s))
         return dot;
     if (dot)
         buf->writeByte('.');

     // Use "this" not "__ctor"
     TemplateDeclaration *td;
     if (s->isCtorDeclaration() || ((td = s->isTemplateDeclaration()) != NULL &&
         td->onemember && td->onemember->isCtorDeclaration()))
     {
         buf->writestring("this");
     }
     else
     {
         /* We just want the identifier, not overloads like TemplateDeclaration::toChars.
          * We don't want the template parameter list and constraints. */
         buf->writestring(s->Dsymbol::toChars());
     }
     return true;
 }

 static void emitAnchor(OutBuffer *buf, Dsymbol *s, Scope *sc)
 {
     Identifier *ident;
     {
         OutBuffer anc;
         emitAnchorName(&anc, s, skipNonQualScopes(sc));
         ident = Identifier::idPool(anc.peekChars());
     }
     size_t *count = (size_t*)dmd_aaGet(&sc->anchorCounts, (void *)ident);
     TemplateDeclaration *td = getEponymousParent(s);
     // don't write an anchor for matching consecutive ditto symbols
     if (*count > 0 && sc->prevAnchor == ident &&
         sc->lastdc && (isDitto(s->comment) || (td && isDitto(td->comment))))
         return;

     (*count)++;
     // cache anchor name
     sc->prevAnchor = ident;

     buf->writestring("$(DDOC_ANCHOR ");
     buf->writestring(ident->toChars());
     // only append count once there's a duplicate
     if (*count != 1)
         buf->printf(".%u", *count);
     buf->writeByte(')');
 }

 /******************************* emitComment **********************************/

 /** Get leading indentation from 'src' which represents lines of code. */
 static size_t getCodeIndent(const char *src)
 {
     while (src && (*src == '\r' || *src == '\n'))
         ++src;  // skip until we find the first non-empty line

     size_t codeIndent = 0;
     while (src && (*src == ' ' || *src == '\t'))
     {
         codeIndent++;
         src++;
     }
     return codeIndent;
 }

 /** Recursively expand template mixin member docs into the scope. */
 static void expandTemplateMixinComments(TemplateMixin *tm, OutBuffer *buf, Scope *sc)
 {
     if (!tm->semanticRun)
         dsymbolSemantic(tm, sc);
     TemplateDeclaration *td = (tm && tm->tempdecl) ?
         tm->tempdecl->isTemplateDeclaration() : NULL;
     if (td && td->members)
     {
         for (size_t i = 0; i < td->members->length; i++)
         {
             Dsymbol *sm = (*td->members)[i];
             TemplateMixin *tmc = sm->isTemplateMixin();
             if (tmc && tmc->comment)
                 expandTemplateMixinComments(tmc, buf, sc);
             else
                 emitComment(sm, buf, sc);
         }
     }
 }

 void emitMemberComments(ScopeDsymbol *sds, OutBuffer *buf, Scope *sc)
 {
     if (!sds->members)
         return;

     //printf("ScopeDsymbol::emitMemberComments() %s\n", toChars());

     const char *m = "$(DDOC_MEMBERS ";
     if (sds->isTemplateDeclaration())
         m = "$(DDOC_TEMPLATE_MEMBERS ";
     else if (sds->isClassDeclaration())
         m = "$(DDOC_CLASS_MEMBERS ";
     else if (sds->isStructDeclaration())
         m = "$(DDOC_STRUCT_MEMBERS ";
     else if (sds->isEnumDeclaration())
         m = "$(DDOC_ENUM_MEMBERS ";
     else if (sds->isModule())
         m = "$(DDOC_MODULE_MEMBERS ";

     size_t offset1 = buf->length();         // save starting offset
     buf->writestring(m);
     size_t offset2 = buf->length();         // to see if we write anything

     sc = sc->push(sds);

     for (size_t i = 0; i < sds->members->length; i++)
     {
         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, buf, sc);

         emitComment(s, buf, sc);
     }
     emitComment(NULL, buf, sc);

     sc->pop();

     if (buf->length() == offset2)
     {
         /* Didn't write out any members, so back out last write
          */
         buf->setsize(offset1);
     }
     else
         buf->writestring(")\n");
 }

 void emitProtection(OutBuffer *buf, Prot prot)
 {
     if (prot.kind != Prot::undefined && prot.kind != Prot::public_)
     {
         protectionToBuffer(buf, prot);
         buf->writeByte(' ');
     }
 }

 void emitComment(Dsymbol *s, OutBuffer *buf, Scope *sc)
 {
     class EmitComment : public Visitor
     {
     public:
         OutBuffer *buf;
         Scope *sc;

         EmitComment(OutBuffer *buf, Scope *sc)
             : buf(buf), sc(sc)
         {
         }

         void visit(Dsymbol *) {}
         void visit(InvariantDeclaration *) {}
         void visit(UnitTestDeclaration *) {}
         void visit(PostBlitDeclaration *) {}
         void visit(DtorDeclaration *) {}
         void visit(StaticCtorDeclaration *) {}
         void visit(StaticDtorDeclaration *) {}
         void visit(TypeInfoDeclaration *) {}

         void emit(Scope *sc, Dsymbol *s, const utf8_t *com)
         {
             if (s && sc->lastdc && isDitto(com))
             {
                 sc->lastdc->a.push(s);
                 return;
             }

             // Put previous doc comment if exists
             if (DocComment *dc = sc->lastdc)
             {
                 // Put the declaration signatures as the document 'title'
                 buf->writestring(ddoc_decl_s);
                 for (size_t i = 0; i < dc->a.length; i++)
                 {
                     Dsymbol *sx = dc->a[i];

                     if (i == 0)
                     {
                         size_t o = buf->length();
                         toDocBuffer(sx, buf, sc);
                         highlightCode(sc, sx, buf, o);
                         continue;
                     }

                     buf->writestring("$(DDOC_DITTO ");
                     {
                         size_t o = buf->length();
                         toDocBuffer(sx, buf, sc);
                         highlightCode(sc, sx, buf, o);
                     }
                     buf->writeByte(')');
                 }
                 buf->writestring(ddoc_decl_e);

                 // Put the ddoc comment as the document 'description'
                 buf->writestring(ddoc_decl_dd_s);
                 {
                     dc->writeSections(sc, &dc->a, buf);
                     if (ScopeDsymbol *sds = dc->a[0]->isScopeDsymbol())
                         emitMemberComments(sds, buf, sc);
                 }
                 buf->writestring(ddoc_decl_dd_e);
                 //printf("buf.2 = [[%.*s]]\n", buf->length() - o0, buf->slice().ptr + o0);
             }

             if (s)
             {
                 DocComment *dc = DocComment::parse(s, com);
                 dc->pmacrotable = &sc->_module->macrotable;
                 sc->lastdc = dc;
             }
         }

         void visit(Declaration *d)
         {
             //printf("Declaration::emitComment(%p '%s'), comment = '%s'\n", d, d->toChars(), d->comment);
             //printf("type = %p\n", d->type);
             const utf8_t *com = d->comment;
             if (TemplateDeclaration *td = getEponymousParent(d))
             {
                 if (isDitto(td->comment))
                     com = td->comment;
                 else
                     com = Lexer::combineComments(td->comment, com);
             }
             else
             {
                 if (!d->ident)
                     return;
                 if (!d->type && !d->isCtorDeclaration() && !d->isAliasDeclaration())
                     return;
                 if (d->protection.kind == Prot::private_ || sc->protection.kind == Prot::private_)
                     return;
             }
             if (!com)
                 return;

             emit(sc, d, com);
         }

         void visit(AggregateDeclaration *ad)
         {
             //printf("AggregateDeclaration::emitComment() '%s'\n", ad->toChars());
             const utf8_t *com = ad->comment;
             if (TemplateDeclaration *td = getEponymousParent(ad))
             {
                 if (isDitto(td->comment))
                     com = td->comment;
                 else
                     com = Lexer::combineComments(td->comment, com);
             }
             else
             {
                 if (ad->prot().kind == Prot::private_ || sc->protection.kind == Prot::private_)
                     return;
                 if (!ad->comment)
                     return;
             }
             if (!com)
                 return;

             emit(sc, ad, com);
         }

         void visit(TemplateDeclaration *td)
         {
             //printf("TemplateDeclaration::emitComment() '%s', kind = %s\n", td->toChars(), td->kind());
             if (td->prot().kind == Prot::private_ || sc->protection.kind == Prot::private_)
                 return;
             if (!td->comment)
                 return;

             if (Dsymbol *ss = getEponymousMember(td))
             {
                 ss->accept(this);
                 return;
             }
             emit(sc, td, td->comment);
         }

         void visit(EnumDeclaration *ed)
         {
             if (ed->prot().kind == Prot::private_ || sc->protection.kind == Prot::private_)
                 return;
             if (ed->isAnonymous() && ed->members)
             {
                 for (size_t i = 0; i < ed->members->length; i++)
                 {
                     Dsymbol *s = (*ed->members)[i];
                     emitComment(s, buf, sc);
                 }
                 return;
             }
             if (!ed->comment)
                 return;
             if (ed->isAnonymous())
                 return;

             emit(sc, ed, ed->comment);
         }

         void visit(EnumMember *em)
         {
             //printf("EnumMember::emitComment(%p '%s'), comment = '%s'\n", em, em->toChars(), em->comment);
             if (em->prot().kind == Prot::private_ || sc->protection.kind == Prot::private_)
                 return;
             if (!em->comment)
                 return;

             emit(sc, em, em->comment);
         }

         void visit(AttribDeclaration *ad)
         {
             //printf("AttribDeclaration::emitComment(sc = %p)\n", sc);

             /* A general problem with this, illustrated by BUGZILLA 2516,
              * is that attributes are not transmitted through to the underlying
              * member declarations for template bodies, because semantic analysis
              * is not done for template declaration bodies
              * (only template instantiations).
              * Hence, Ddoc omits attributes from template members.
              */

             Dsymbols *d = ad->include(NULL);

             if (d)
             {
                 for (size_t i = 0; i < d->length; i++)
                 {
                     Dsymbol *s = (*d)[i];
                     //printf("AttribDeclaration::emitComment %s\n", s->toChars());
                     emitComment(s, buf, sc);
                 }
             }
         }

         void visit(ProtDeclaration *pd)
         {
             if (pd->decl)
             {
                 Scope *scx = sc;
                 sc = sc->copy();
                 sc->protection = pd->protection;
                 visit((AttribDeclaration *)pd);
                 scx->lastdc = sc->lastdc;
                 sc = sc->pop();
             }
         }

         void visit(ConditionalDeclaration *cd)
         {
             //printf("ConditionalDeclaration::emitComment(sc = %p)\n", sc);
             if (cd->condition->inc)
             {
                 visit((AttribDeclaration *)cd);
                 return;
             }

             /* If generating doc comment, be careful because if we're inside
              * a template, then include(NULL) will fail.
              */
             Dsymbols *d = cd->decl ? cd->decl : cd->elsedecl;
             for (size_t i = 0; i < d->length; i++)
             {
                 Dsymbol *s = (*d)[i];
                 emitComment(s, buf, sc);
             }
         }
     };

     EmitComment v(buf, sc);

     if (!s)
         v.emit(sc, NULL, NULL);
     else
         s->accept(&v);
 }

 /******************************* toDocBuffer **********************************/

 void toDocBuffer(Dsymbol *s, OutBuffer *buf, Scope *sc)
 {
     class ToDocBuffer : public Visitor
     {
     public:
         OutBuffer *buf;
         Scope *sc;

         ToDocBuffer(OutBuffer *buf, Scope *sc)
             : buf(buf), sc(sc)
         {
         }

         void visit(Dsymbol *s)
         {
             //printf("Dsymbol::toDocbuffer() %s\n", s->toChars());
             HdrGenState hgs;
             hgs.ddoc = true;
             ::toCBuffer(s, buf, &hgs);
         }

         void prefix(Dsymbol *s)
         {
             if (s->isDeprecated())
                 buf->writestring("deprecated ");

             if (Declaration *d = s->isDeclaration())
             {
                 emitProtection(buf, d->protection);

                 if (d->isStatic())
                     buf->writestring("static ");
                 else if (d->isFinal())
                     buf->writestring("final ");
                 else if (d->isAbstract())
                     buf->writestring("abstract ");

                 if (!d->isFuncDeclaration())  // functionToBufferFull handles this
                 {
                     if (d->isConst())
                         buf->writestring("const ");
                     if (d->isImmutable())
                         buf->writestring("immutable ");
                     if (d->isSynchronized())
                         buf->writestring("synchronized ");

                     if (d->storage_class & STCmanifest)
                         buf->writestring("enum ");
                 }
             }
         }

         void visit(Declaration *d)
         {
             if (!d->ident)
                 return;

             TemplateDeclaration *td = getEponymousParent(d);
             //printf("Declaration::toDocbuffer() %s, originalType = %s, td = %s\n", d->toChars(), d->originalType ? d->originalType->toChars() : "--", td ? td->toChars() : "--");

             HdrGenState hgs;
             hgs.ddoc = true;

             if (d->isDeprecated())
                 buf->writestring("$(DEPRECATED ");

             prefix(d);

             if (d->type)
             {
                 Type *origType = d->originalType ? d->originalType : d->type;
                 if (origType->ty == Tfunction)
                 {
                     functionToBufferFull((TypeFunction *)origType, buf, d->ident, &hgs, td);
                 }
                 else
                     ::toCBuffer(origType, buf, d->ident, &hgs);
             }
             else
                 buf->writestring(d->ident->toChars());

             if (d->isVarDeclaration() && td)
             {
                 buf->writeByte('(');
                 if (td->origParameters && td->origParameters->length)
                 {
                     for (size_t i = 0; i < td->origParameters->length; i++)
                     {
                         if (i)
                             buf->writestring(", ");
                         toCBuffer((*td->origParameters)[i], buf, &hgs);
                     }
                 }
                 buf->writeByte(')');
             }

             // emit constraints if declaration is a templated declaration
             if (td && td->constraint)
             {
                 buf->writestring(" if (");
                 ::toCBuffer(td->constraint, buf, &hgs);
                 buf->writeByte(')');
             }

             if (d->isDeprecated())
                 buf->writestring(")");

             buf->writestring(";\n");
         }

         void visit(AliasDeclaration *ad)
         {
             //printf("AliasDeclaration::toDocbuffer() %s\n", ad->toChars());
             if (!ad->ident)
                 return;

             if (ad->isDeprecated())
                 buf->writestring("deprecated ");

             emitProtection(buf, ad->protection);
             buf->printf("alias %s = ", ad->toChars());

             if (Dsymbol *sa = ad->aliassym)  // ident alias
             {
                 prettyPrintDsymbol(sa, ad->parent);
             }
             else if (Type *type = ad->getType())  // type alias
             {
                 if (type->ty == Tclass || type->ty == Tstruct || type->ty == Tenum)
                 {
                     if (Dsymbol *s = type->toDsymbol(NULL))  // elaborate type
                         prettyPrintDsymbol(s, ad->parent);
                     else
                         buf->writestring(type->toChars());
                 }
                 else
                 {
                     // simple type
                     buf->writestring(type->toChars());
                 }
             }

             buf->writestring(";\n");
         }

         void parentToBuffer(Dsymbol *s)
         {
             if (s && !s->isPackage() && !s->isModule())
             {
                 parentToBuffer(s->parent);
                 buf->writestring(s->toChars());
                 buf->writestring(".");
             }
         }

         static bool inSameModule(Dsymbol *s, Dsymbol *p)
         {
             for ( ; s ; s = s->parent)
             {
                 if (s->isModule())
                     break;
             }

             for ( ; p ; p = p->parent)
             {
                 if (p->isModule())
                     break;
             }

             return s == p;
         }

         void prettyPrintDsymbol(Dsymbol *s, Dsymbol *parent)
         {
             if (s->parent && (s->parent == parent))  // in current scope -> naked name
             {
                 buf->writestring(s->toChars());
             }
             else if (!inSameModule(s, parent))  // in another module -> full name
             {
                 buf->writestring(s->toPrettyChars());
             }
             else  // nested in a type in this module -> full name w/o module name
             {
                 // if alias is nested in a user-type use module-scope lookup
                 if (!parent->isModule() && !parent->isPackage())
                     buf->writestring(".");

                 parentToBuffer(s->parent);
                 buf->writestring(s->toChars());
             }
         }

         void visit(AggregateDeclaration *ad)
         {
             if (!ad->ident)
                 return;

             buf->printf("%s %s", ad->kind(), ad->toChars());
             buf->writestring(";\n");
         }

         void visit(StructDeclaration *sd)
         {
             //printf("StructDeclaration::toDocbuffer() %s\n", sd->toChars());
             if (!sd->ident)
                 return;

             if (TemplateDeclaration *td = getEponymousParent(sd))
             {
                 toDocBuffer(td, buf, sc);
             }
             else
             {
                 buf->printf("%s %s", sd->kind(), sd->toChars());
             }
             buf->writestring(";\n");
         }

         void visit(ClassDeclaration *cd)
         {
             //printf("ClassDeclaration::toDocbuffer() %s\n", cd->toChars());
             if (!cd->ident)
                 return;

             if (TemplateDeclaration *td = getEponymousParent(cd))
             {
                 toDocBuffer(td, buf, sc);
             }
             else
             {
                 if (!cd->isInterfaceDeclaration() && cd->isAbstract())
                     buf->writestring("abstract ");
                 buf->printf("%s %s", cd->kind(), cd->toChars());
             }
             int any = 0;
             for (size_t i = 0; i < cd->baseclasses->length; i++)
             {
                 BaseClass *bc = (*cd->baseclasses)[i];

                 if (bc->sym && bc->sym->ident == Id::Object)
                     continue;

                 if (any)
                     buf->writestring(", ");
                 else
                 {
                     buf->writestring(": ");
                     any = 1;
                 }
                 emitProtection(buf, Prot(Prot::public_));
                 if (bc->sym)
                 {
                     buf->printf("$(DDOC_PSUPER_SYMBOL %s)", bc->sym->toPrettyChars());
                 }
                 else
                 {
                     HdrGenState hgs;
                     ::toCBuffer(bc->type, buf, NULL, &hgs);
                 }
             }
             buf->writestring(";\n");
         }

         void visit(EnumDeclaration *ed)
         {
             if (!ed->ident)
                 return;

             buf->printf("%s %s", ed->kind(), ed->toChars());
             if (ed->memtype)
             {
                 buf->writestring(": $(DDOC_ENUM_BASETYPE ");
                 HdrGenState hgs;
                 ::toCBuffer(ed->memtype, buf, NULL, &hgs);
                 buf->writestring(")");
             }
             buf->writestring(";\n");
         }

         void visit(EnumMember *em)
         {
             if (!em->ident)
                 return;

             buf->writestring(em->toChars());
         }
     };

     ToDocBuffer v(buf, sc);
     s->accept(&v);
 }

 /********************************* DocComment *********************************/

 DocComment *DocComment::parse(Dsymbol *s, const utf8_t *comment)
 {
     //printf("parse(%s): '%s'\n", s->toChars(), comment);
     DocComment *dc = new DocComment();
     dc->a.push(s);
     if (!comment)
         return dc;

     dc->parseSections(comment);

     for (size_t i = 0; i < dc->sections.length; i++)
     {
         Section *sec = dc->sections[i];

         if (icmp("copyright", sec->name, sec->namelen) == 0)
         {
             dc->copyright = sec;
         }
         if (icmp("macros", sec->name, sec->namelen) == 0)
         {
             dc->macros = sec;
         }
     }

     return dc;
 }

 /*****************************************
  * Parse next paragraph out of *pcomment.
  * Update *pcomment to point past paragraph.
  * Returns NULL if no more paragraphs.
  * If paragraph ends in 'identifier:',
  * then (*pcomment)[0 .. idlen] is the identifier.
  */

 void DocComment::parseSections(const utf8_t *comment)
 {
     const utf8_t *p;
     const utf8_t *pstart;
     const utf8_t *pend;
     const utf8_t *idstart = NULL;       // dead-store to prevent spurious warning
     size_t idlen;

     const utf8_t *name = NULL;
     size_t namelen = 0;

     //printf("parseSections('%s')\n", comment);
     p = comment;
     while (*p)
     {
         const utf8_t *pstart0 = p;
         p = skipwhitespace(p);
         pstart = p;
         pend = p;

         /* Find end of section, which is ended by one of:
          *      'identifier:' (but not inside a code section)
          *      '\0'
          */
         idlen = 0;
         int inCode = 0;
         while (1)
         {
             // Check for start/end of a code section
             if (*p == '-')
             {
                 if (!inCode)
                 {
                     // restore leading indentation
                     while (pstart0 < pstart && isIndentWS(pstart-1)) --pstart;
                 }

                 int numdash = 0;
                 while (*p == '-')
                 {
                     ++numdash;
                     p++;
                 }
                 // BUG: handle UTF PS and LS too
                 if ((!*p || *p == '\r' || *p == '\n') && numdash >= 3)
                     inCode ^= 1;
                 pend = p;
             }

             if (!inCode && isIdStart(p))
             {
                 const utf8_t *q = p + utfStride(p);
                 while (isIdTail(q))
                     q += utfStride(q);
                 // Detected tag ends it
                 if (*q == ':' && isupper(*p)
                         && (isspace(q[1]) || q[1] == 0))
                 {
                     idlen = q - p;
                     idstart = p;
                     for (pend = p; pend > pstart; pend--)
                     {
                         if (pend[-1] == '\n')
                             break;
                     }
                     p = q + 1;
                     break;
                 }
             }
             while (1)
             {
                 if (!*p)
                     goto L1;
                 if (*p == '\n')
                 {
                     p++;
                     if (*p == '\n' && !summary && !namelen && !inCode)
                     {
                         pend = p;
                         p++;
                         goto L1;
                     }
                     break;
                 }
                 p++;
                 pend = p;
             }
             p = skipwhitespace(p);
         }
       L1:

         if (namelen || pstart < pend)
         {
             Section *s;
             if (icmp("Params", name, namelen) == 0)
                 s = new ParamSection();
             else if (icmp("Macros", name, namelen) == 0)
                 s = new MacroSection();
             else
                 s = new Section();
             s->name = name;
             s->namelen = namelen;
             s->body = pstart;
             s->bodylen = pend - pstart;
             s->nooutput = 0;

             //printf("Section: '%.*s' = '%.*s'\n", s->namelen, s->name, s->bodylen, s->body);

             sections.push(s);

             if (!summary && !namelen)
                 summary = s;
         }

         if (idlen)
         {
             name = idstart;
             namelen = idlen;
         }
         else
         {
             name = NULL;
             namelen = 0;
             if (!*p)
                 break;
         }
     }
 }

 void DocComment::writeSections(Scope *sc, Dsymbols *a, OutBuffer *buf)
 {
     assert(a->length);

     //printf("DocComment::writeSections()\n");
     Loc loc = (*a)[0]->loc;
     if (Module *m = (*a)[0]->isModule())
     {
         if (m->md)
             loc = m->md->loc;
     }

     size_t offset1 = buf->length();
     buf->writestring("$(DDOC_SECTIONS ");
     size_t offset2 = buf->length();

     for (size_t i = 0; i < sections.length; i++)
     {
         Section *sec = sections[i];
         if (sec->nooutput)
             continue;

         //printf("Section: '%.*s' = '%.*s'\n", sec->namelen, sec->name, sec->bodylen, sec->body);
         if (!sec->namelen && i == 0)
         {
             buf->writestring("$(DDOC_SUMMARY ");
             size_t o = buf->length();
             buf->write(sec->body, sec->bodylen);
             escapeStrayParenthesis(loc, buf, o);
             highlightText(sc, a, buf, o);
             buf->writestring(")\n");
         }
         else
             sec->write(loc, this, sc, a, buf);
     }

     for (size_t i = 0; i < a->length; i++)
     {
         Dsymbol *s = (*a)[i];
         if (Dsymbol *td = getEponymousParent(s))
             s = td;

         for (UnitTestDeclaration *utd = s->ddocUnittest; utd; utd = utd->ddocUnittest)
         {
             if (utd->protection.kind == Prot::private_ || !utd->comment || !utd->fbody)
                 continue;

             // Strip whitespaces to avoid showing empty summary
             const utf8_t *c = utd->comment;
             while (*c == ' ' || *c == '\t' || *c == '\n' || *c == '\r') ++c;

             buf->writestring("$(DDOC_EXAMPLES ");

             size_t o = buf->length();
             buf->writestring((const char *)c);

             if (utd->codedoc)
             {
                 size_t n = getCodeIndent(utd->codedoc);
                 while (n--) buf->writeByte(' ');
                 buf->writestring("----\n");
                 buf->writestring(utd->codedoc);
                 buf->writestring("----\n");
                 highlightText(sc, a, buf, o);
             }

             buf->writestring(")");
         }
     }

     if (buf->length() == offset2)
     {
         /* Didn't write out any sections, so back out last write
          */
         buf->setsize(offset1);
         buf->writestring("$(DDOC_BLANKLINE)\n");
     }
     else
         buf->writestring(")\n");
 }

 /***************************************************
  */

 void Section::write(Loc loc, DocComment *, Scope *sc, Dsymbols *a, OutBuffer *buf)
 {
     assert(a->length);

     if (namelen)
     {
         static const char *table[] =
         {
             "AUTHORS", "BUGS", "COPYRIGHT", "DATE",
             "DEPRECATED", "EXAMPLES", "HISTORY", "LICENSE",
             "RETURNS", "SEE_ALSO", "STANDARDS", "THROWS",
             "VERSION", NULL
         };

         for (size_t i = 0; table[i]; i++)
         {
             if (icmp(table[i], name, namelen) == 0)
             {
                 buf->printf("$(DDOC_%s ", table[i]);
                 goto L1;
             }
         }

         buf->writestring("$(DDOC_SECTION ");

             // Replace _ characters with spaces
             buf->writestring("$(DDOC_SECTION_H ");
             size_t o = buf->length();
             for (size_t u = 0; u < namelen; u++)
             {
                 utf8_t c = name[u];
                 buf->writeByte((c == '_') ? ' ' : c);
             }
             escapeStrayParenthesis(loc, buf, o);
             buf->writestring(":)\n");
     }
     else
     {
         buf->writestring("$(DDOC_DESCRIPTION ");
     }
   L1:
     size_t o = buf->length();
     buf->write(body, bodylen);
     escapeStrayParenthesis(loc, buf, o);
     highlightText(sc, a, buf, o);
     buf->writestring(")\n");
 }

 /***************************************************
  */

 void ParamSection::write(Loc loc, DocComment *, Scope *sc, Dsymbols *a, OutBuffer *buf)
 {
     assert(a->length);
     Dsymbol *s = (*a)[0];   // test

     const utf8_t *p = body;
     size_t len = bodylen;
     const utf8_t *pend = p + len;

     const utf8_t *tempstart = NULL;
     size_t templen = 0;

     const utf8_t *namestart = NULL;
     size_t namelen = 0;       // !=0 if line continuation

     const utf8_t *textstart = NULL;
     size_t textlen = 0;

     size_t paramcount = 0;

     buf->writestring("$(DDOC_PARAMS ");
     while (p < pend)
     {
         // Skip to start of macro
         while (1)
         {
             switch (*p)
             {
                 case ' ':
                 case '\t':
                     p++;
                     continue;

                 case '\n':
                     p++;
                     goto Lcont;

                 default:
                     if (isIdStart(p) || isCVariadicArg(p, pend - p))
                         break;
                     if (namelen)
                         goto Ltext;             // continuation of prev macro
                     goto Lskipline;
             }
             break;
         }
         tempstart = p;

         while (isIdTail(p))
             p += utfStride(p);
         if (isCVariadicArg(p, pend - p))
             p += 3;

         templen = p - tempstart;

         while (*p == ' ' || *p == '\t')
             p++;

         if (*p != '=')
         {
             if (namelen)
                 goto Ltext;             // continuation of prev macro
             goto Lskipline;
         }
         p++;

         if (namelen)
         {
             // Output existing param

         L1:
             //printf("param '%.*s' = '%.*s'\n", namelen, namestart, textlen, textstart);
             ++paramcount;
             HdrGenState hgs;
             buf->writestring("$(DDOC_PARAM_ROW ");
             {
                 buf->writestring("$(DDOC_PARAM_ID ");
                 {
                     size_t o = buf->length();
                     Parameter *fparam = isFunctionParameter(a, namestart, namelen);
                     if (!fparam)
                     {
                         // Comments on a template might refer to function parameters within.
                         // Search the parameters of nested eponymous functions (with the same name.)
                         fparam = isEponymousFunctionParameter(a, namestart, namelen);
                     }
                     bool isCVariadic = isCVariadicParameter(a, namestart, namelen);
                     if (isCVariadic)
                     {
                         buf->writestring("...");
                     }
                     else if (fparam && fparam->type && fparam->ident)
                     {
                         ::toCBuffer(fparam->type, buf, fparam->ident, &hgs);
                     }
                     else
                     {
                         if (isTemplateParameter(a, namestart, namelen))
                         {
                             // 10236: Don't count template parameters for params check
                             --paramcount;
                         }
                         else if (!fparam)
                         {
                             warning(s->loc, "Ddoc: function declaration has no parameter '%.*s'", (int)namelen, namestart);
                         }
                         buf->write(namestart, namelen);
                     }
                     escapeStrayParenthesis(loc, buf, o);
                     highlightCode(sc, a, buf, o);
                 }
                 buf->writestring(")\n");

                 buf->writestring("$(DDOC_PARAM_DESC ");
                 {
                     size_t o = buf->length();
                     buf->write(textstart, textlen);
                     escapeStrayParenthesis(loc, buf, o);
                     highlightText(sc, a, buf, o);
                 }
                 buf->writestring(")");
             }
             buf->writestring(")\n");
             namelen = 0;
             if (p >= pend)
                 break;
         }

         namestart = tempstart;
         namelen = templen;

         while (*p == ' ' || *p == '\t')
             p++;
         textstart = p;

       Ltext:
         while (*p != '\n')
             p++;
         textlen = p - textstart;
         p++;

      Lcont:
         continue;

      Lskipline:
         // Ignore this line
         while (*p++ != '\n')
             ;
     }
     if (namelen)
         goto L1;                // write out last one
     buf->writestring(")\n");

     TypeFunction *tf = a->length == 1 ? isTypeFunction(s) : NULL;
     if (tf)
     {
         size_t pcount = (tf->parameterList.parameters ? tf->parameterList.parameters->length : 0) +
                         (int)(tf->parameterList.varargs == VARARGvariadic);
         if (pcount != paramcount)
         {
             warning(s->loc, "Ddoc: parameter count mismatch");
         }
     }
 }

 /***************************************************
  */

 void MacroSection::write(Loc, DocComment *dc, Scope *, Dsymbols *, OutBuffer *)
 {
     //printf("MacroSection::write()\n");
     DocComment::parseMacros(dc->pescapetable, dc->pmacrotable, body, bodylen);
 }

 /************************************************
  * Parse macros out of Macros: section.
  * Macros are of the form:
  *      name1 = value1
  *
  *      name2 = value2
  */

 void DocComment::parseMacros(Escape **pescapetable, Macro **pmacrotable, const utf8_t *m, size_t mlen)
 {
     const utf8_t *p = m;
     size_t len = mlen;
     const utf8_t *pend = p + len;

     const utf8_t *tempstart = NULL;
     size_t templen = 0;

     const utf8_t *namestart = NULL;
     size_t namelen = 0;       // !=0 if line continuation

     const utf8_t *textstart = NULL;
     size_t textlen = 0;

     while (p < pend)
     {
         // Skip to start of macro
         while (1)
         {
             if (p >= pend)
                 goto Ldone;
             switch (*p)
             {
                 case ' ':
                 case '\t':
                     p++;
                     continue;

                 case '\r':
                 case '\n':
                     p++;
                     goto Lcont;

                 default:
                     if (isIdStart(p))
                         break;
                     if (namelen)
                         goto Ltext;             // continuation of prev macro
                     goto Lskipline;
             }
             break;
         }
         tempstart = p;

         while (1)
         {
             if (p >= pend)
                 goto Ldone;
             if (!isIdTail(p))
                 break;
             p += utfStride(p);
         }
         templen = p - tempstart;

         while (1)
         {
             if (p >= pend)
                 goto Ldone;
             if (!(*p == ' ' || *p == '\t'))
                 break;
             p++;
         }

         if (*p != '=')
         {
             if (namelen)
                 goto Ltext;             // continuation of prev macro
             goto Lskipline;
         }
         p++;
         if (p >= pend)
             goto Ldone;

         if (namelen)
         {
             // Output existing macro
         L1:
             //printf("macro '%.*s' = '%.*s'\n", namelen, namestart, textlen, textstart);
             if (icmp("ESCAPES", namestart, namelen) == 0)
                 parseEscapes(pescapetable, textstart, textlen);
             else
                 Macro::define(pmacrotable, namestart, namelen, textstart, textlen);
             namelen = 0;
             if (p >= pend)
                 break;
         }

         namestart = tempstart;
         namelen = templen;

         while (p < pend && (*p == ' ' || *p == '\t'))
             p++;
         textstart = p;

       Ltext:
         while (p < pend && *p != '\r' && *p != '\n')
             p++;
         textlen = p - textstart;

         p++;
         //printf("p = %p, pend = %p\n", p, pend);

      Lcont:
         continue;

      Lskipline:
         // Ignore this line
         while (p < pend && *p != '\r' && *p != '\n')
             p++;
     }
 Ldone:
     if (namelen)
         goto L1;                // write out last one
 }

 /**************************************
  * Parse escapes of the form:
  *      /c/string/
  * where c is a single character.
  * Multiple escapes can be separated
  * by whitespace and/or commas.
  */

 void DocComment::parseEscapes(Escape **pescapetable, const utf8_t *textstart, size_t textlen)
 {
     Escape *escapetable = *pescapetable;

     if (!escapetable)
     {
         escapetable = new Escape;
         memset(escapetable, 0, sizeof(Escape));
         *pescapetable = escapetable;
     }
     //printf("parseEscapes('%.*s') pescapetable = %p\n", textlen, textstart, pescapetable);
     const utf8_t *p = textstart;
     const utf8_t *pend = p + textlen;

     while (1)
     {
         while (1)
         {
             if (p + 4 >= pend)
                 return;
             if (!(*p == ' ' || *p == '\t' || *p == '\r' || *p == '\n' || *p == ','))
                 break;
             p++;
         }
         if (p[0] != '/' || p[2] != '/')
             return;
         utf8_t c = p[1];
         p += 3;
         const utf8_t *start = p;
         while (1)
         {
             if (p >= pend)
                 return;
             if (*p == '/')
                 break;
             p++;
         }
         size_t len = p - start;
         char *s = (char *)memcpy(mem.xmalloc(len + 1), start, len);
         s[len] = 0;
         escapetable->strings[c] = s;
         //printf("\t%c = '%s'\n", c, s);
         p++;
     }
 }


 /******************************************
  * Compare 0-terminated string with length terminated string.
  * Return < 0, ==0, > 0
  */

 int cmp(const char *stringz, const void *s, size_t slen)
 {
     size_t len1 = strlen(stringz);

     if (len1 != slen)
         return (int)(len1 - slen);
     return memcmp(stringz, s, slen);
 }

 int icmp(const char *stringz, const void *s, size_t slen)
 {
     size_t len1 = strlen(stringz);

     if (len1 != slen)
         return (int)(len1 - slen);
     return Port::memicmp(stringz, (const char *)s, slen);
 }

 /*****************************************
  * Return true if comment consists entirely of "ditto".
  */

 bool isDitto(const utf8_t *comment)
 {
     if (comment)
     {
         const utf8_t *p = skipwhitespace(comment);

         if (Port::memicmp((const char *)p, "ditto", 5) == 0 && *skipwhitespace(p + 5) == 0)
             return true;
     }
     return false;
 }

 /**********************************************
  * Skip white space.
  */

 const utf8_t *skipwhitespace(const utf8_t *p)
 {
     for (; 1; p++)
     {
         switch (*p)
         {
             case ' ':
             case '\t':
             case '\n':
                 continue;
         }
         break;
     }
     return p;
 }


 /************************************************
  * Scan forward to one of:
  *      start of identifier
  *      beginning of next line
  *      end of buf
  */

 size_t skiptoident(OutBuffer *buf, size_t i)
 {
     while (i < buf->length())
     {
         dchar_t c;

         size_t oi = i;
         if (utf_decodeChar((utf8_t *)buf->slice().ptr, buf->length(), &i, &c))
         {
             /* Ignore UTF errors, but still consume input
              */
             break;
         }
         if (c >= 0x80)
         {
             if (!isUniAlpha(c))
                 continue;
         }
         else if (!(isalpha(c) || c == '_' || c == '\n'))
             continue;
         i = oi;
         break;
     }
     return i;
 }

 /************************************************
  * Scan forward past end of identifier.
  */

 size_t skippastident(OutBuffer *buf, size_t i)
 {
     while (i < buf->length())
     {
         dchar_t c;

         size_t oi = i;
         if (utf_decodeChar((utf8_t *)buf->slice().ptr, buf->length(), &i, &c))
         {
             /* Ignore UTF errors, but still consume input
              */
             break;
         }
         if (c >= 0x80)
         {
             if (isUniAlpha(c))
                 continue;
         }
         else if (isalnum(c) || c == '_')
             continue;
         i = oi;
         break;
     }
     return i;
 }


 /************************************************
  * Scan forward past URL starting at i.
  * We don't want to highlight parts of a URL.
  * Returns:
  *      i if not a URL
  *      index just past it if it is a URL
  */

 size_t skippastURL(OutBuffer *buf, size_t i)
 {
     size_t length = buf->length() - i;
     utf8_t *p = (utf8_t *)&buf->slice().ptr[i];
     size_t j;
     unsigned sawdot = 0;

     if (length > 7 && Port::memicmp((char *)p, "http://", 7) == 0)
     {
         j = 7;
     }
     else if (length > 8 && Port::memicmp((char *)p, "https://", 8) == 0)
     {
         j = 8;
     }
     else
         goto Lno;

     for (; j < length; j++)
     {
         utf8_t c = p[j];
         if (isalnum(c))
             continue;
         if (c == '-' || c == '_' || c == '?' ||
             c == '=' || c == '%' || c == '&' ||
             c == '/' || c == '+' || c == '#' ||
             c == '~')
             continue;
         if (c == '.')
         {
             sawdot = 1;
             continue;
         }
         break;
     }
     if (sawdot)
         return i + j;

 Lno:
     return i;
 }


 /****************************************************
  */

 bool isIdentifier(Dsymbols *a, const utf8_t *p, size_t len)
 {
     for (size_t i = 0; i < a->length; i++)
     {
         const char *s = (*a)[i]->ident->toChars();
         if (cmp(s, p, len) == 0)
             return true;
     }
     return false;
 }

 /****************************************************
  */

 bool isKeyword(utf8_t *p, size_t len)
 {
     static const char *table[] = { "true", "false", "null", NULL };

     for (int i = 0; table[i]; i++)
     {
         if (cmp(table[i], p, len) == 0)
             return true;
     }
     return false;
 }

 /****************************************************
  */

 TypeFunction *isTypeFunction(Dsymbol *s)
 {
     FuncDeclaration *f = s->isFuncDeclaration();

     /* f->type may be NULL for template members.
      */
     if (f && f->type)
     {
         Type *t = f->originalType ? f->originalType : f->type;
         if (t->ty == Tfunction)
             return (TypeFunction *)t;
     }
     return NULL;
 }

 /****************************************************
  */

 Parameter *isFunctionParameter(Dsymbols *a, const utf8_t *p, size_t len)
 {
     for (size_t i = 0; i < a->length; i++)
     {
         Parameter *fparam = isFunctionParameter((*a)[i], p, len);
         if (fparam)
         {
             return fparam;
         }
     }
     return NULL;
 }

 /****************************************************
  */

 TemplateParameter *isTemplateParameter(Dsymbols *a, const utf8_t *p, size_t len)
 {
     for (size_t i = 0; i < a->length; i++)
     {
         TemplateDeclaration *td = (*a)[i]->isTemplateDeclaration();
         // Check for the parent, if the current symbol is not a template declaration.
         if (!td)
             td = getEponymousParent((*a)[i]);
         if (td && td->origParameters)
         {
             for (size_t k = 0; k < td->origParameters->length; k++)
             {
                 TemplateParameter *tp = (*td->origParameters)[k];
                 if (tp->ident && cmp(tp->ident->toChars(), p, len) == 0)
                 {
                     return tp;
                 }
             }
         }
     }
     return NULL;
 }

 /****************************************************
  * Return true if str is a reserved symbol name
  * that starts with a double underscore.
  */

 bool isReservedName(utf8_t *str, size_t len)
 {
     static const char *table[] = {
         "__ctor", "__dtor", "__postblit", "__invariant", "__unitTest",
         "__require", "__ensure", "__dollar", "__ctfe", "__withSym", "__result",
         "__returnLabel", "__vptr", "__monitor", "__gate", "__xopEquals", "__xopCmp",
         "__LINE__", "__FILE__", "__MODULE__", "__FUNCTION__", "__PRETTY_FUNCTION__",
         "__DATE__", "__TIME__", "__TIMESTAMP__", "__VENDOR__", "__VERSION__",
         "__EOF__", "__LOCAL_SIZE", "___tls_get_addr", "__entrypoint", NULL };

     for (int i = 0; table[i]; i++)
     {
         if (cmp(table[i], str, len) == 0)
             return true;
     }
     return false;
 }

 /**************************************************
  * Highlight text section.
  */

 void highlightText(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset)
 {
     Dsymbol *s = a->length ? (*a)[0] : NULL;   // test

     //printf("highlightText()\n");

     int leadingBlank = 1;
     int inCode = 0;
     int inBacktick = 0;
     //int inComment = 0;                  // in <!-- ... --> comment
     size_t iCodeStart = 0;                    // start of code section
     size_t codeIndent = 0;

     size_t iLineStart = offset;

     for (size_t i = offset; i < buf->length(); i++)
     {
         utf8_t c = buf->slice().ptr[i];

      Lcont:
         switch (c)
         {
             case ' ':
             case '\t':
                 break;

             case '\n':
                 if (inBacktick)
                 {
                     // `inline code` is only valid if contained on a single line
                     // otherwise, the backticks should be output literally.
                     //
                     // This lets things like `output from the linker' display
                     // unmolested while keeping the feature consistent with GitHub.

                     inBacktick = false;
                     inCode = false; // the backtick also assumes we're in code

                     // Nothing else is necessary since the DDOC_BACKQUOTED macro is
                     // inserted lazily at the close quote, meaning the rest of the
                     // text is already OK.
                 }

                 if (!sc->_module->isDocFile &&
                     !inCode && i == iLineStart && i + 1 < buf->length())    // if "\n\n"
                 {
                     static const char blankline[] = "$(DDOC_BLANKLINE)\n";

                     i = buf->insert(i, blankline, strlen(blankline));
                 }
                 leadingBlank = 1;
                 iLineStart = i + 1;
                 break;

             case '<':
             {
                 leadingBlank = 0;
                 if (inCode)
                     break;
                 utf8_t *p = (utf8_t *)&buf->slice().ptr[i];
                 const char *se = sc->_module->escapetable->escapeChar('<');
                 if (se && strcmp(se, "&lt;") == 0)
                 {
                     // Generating HTML
                     // Skip over comments
                     if (p[1] == '!' && p[2] == '-' && p[3] == '-')
                     {
                         size_t j = i + 4;
                         p += 4;
                         while (1)
                         {
                             if (j == buf->length())
                                 goto L1;
                             if (p[0] == '-' && p[1] == '-' && p[2] == '>')
                             {
                                 i = j + 2;  // place on closing '>'
                                 break;
                             }
                             j++;
                             p++;
                         }
                         break;
                     }

                     // Skip over HTML tag
                     if (isalpha(p[1]) || (p[1] == '/' && isalpha(p[2])))
                     {
                         size_t j = i + 2;
                         p += 2;
                         while (1)
                         {
                             if (j == buf->length())
                                 break;
                             if (p[0] == '>')
                             {
                                 i = j;      // place on closing '>'
                                 break;
                             }
                             j++;
                             p++;
                         }
                         break;
                     }
                 }
             L1:
                 // Replace '<' with '&lt;' character entity
                 if (se)
                 {
                     size_t len = strlen(se);
                     buf->remove(i, 1);
                     i = buf->insert(i, se, len);
                     i--;        // point to ';'
                 }
                 break;
             }
             case '>':
             {
                 leadingBlank = 0;
                 if (inCode)
                     break;
                 // Replace '>' with '&gt;' character entity
                 const char *se = sc->_module->escapetable->escapeChar('>');
                 if (se)
                 {
                     size_t len = strlen(se);
                     buf->remove(i, 1);
                     i = buf->insert(i, se, len);
                     i--;        // point to ';'
                 }
                 break;
             }
             case '&':
             {
                 leadingBlank = 0;
                 if (inCode)
                     break;
                 utf8_t *p = (utf8_t *)&buf->slice().ptr[i];
                 if (p[1] == '#' || isalpha(p[1]))
                     break;                      // already a character entity
                 // Replace '&' with '&amp;' character entity
                 const char *se = sc->_module->escapetable->escapeChar('&');
                 if (se)
                 {
                     size_t len = strlen(se);
                     buf->remove(i, 1);
                     i = buf->insert(i, se, len);
                     i--;        // point to ';'
                 }
                 break;
             }
             case '`':
             {
                 if (inBacktick)
                 {
                     inBacktick = 0;
                     inCode = 0;

                     OutBuffer codebuf;

                     codebuf.write(buf->slice().ptr + iCodeStart + 1, i - (iCodeStart + 1));

                     // escape the contents, but do not perform highlighting except for DDOC_PSYMBOL
                     highlightCode(sc, a, &codebuf, 0);

                     buf->remove(iCodeStart, i - iCodeStart + 1); // also trimming off the current `

                     static const char pre[] = "$(DDOC_BACKQUOTED ";
                     i = buf->insert(iCodeStart, pre, strlen(pre));
                     i = buf->insert(i, (char *)codebuf.slice().ptr, codebuf.length());
                     i = buf->insert(i, ")", 1);

                     i--; // point to the ending ) so when the for loop does i++, it will see the next character

                     break;
                 }

                 if (inCode)
                     break;

                 inCode = 1;
                 inBacktick = 1;
                 codeIndent = 0; // inline code is not indented

                 // All we do here is set the code flags and record
                 // the location. The macro will be inserted lazily
                 // so we can easily cancel the inBacktick if we come
                 // across a newline character.
                 iCodeStart = i;

                 break;
             }
             case '-':
                 /* A line beginning with --- delimits a code section.
                  * inCode tells us if it is start or end of a code section.
                  */
                 if (leadingBlank)
                 {
                     size_t istart = i;
                     size_t eollen = 0;

                     leadingBlank = 0;
                     while (1)
                     {
                         ++i;
                         if (i >= buf->length())
                             break;
                         c = buf->slice().ptr[i];
                         if (c == '\n')
                         {
                             eollen = 1;
                             break;
                         }
                         if (c == '\r')
                         {
                             eollen = 1;
                             if (i + 1 >= buf->length())
                                 break;
                             if (buf->slice().ptr[i + 1] == '\n')
                             {
                                 eollen = 2;
                                 break;
                             }
                         }
                         // BUG: handle UTF PS and LS too
                         if (c != '-')
                             goto Lcont;
                     }
                     if (i - istart < 3)
                         goto Lcont;

                     // We have the start/end of a code section

                     // Remove the entire --- line, including blanks and \n
                     buf->remove(iLineStart, i - iLineStart + eollen);
                     i = iLineStart;

                     if (inCode && (i <= iCodeStart))
                     {
                         // Empty code section, just remove it completely.
                         inCode = 0;
                         break;
                     }

                     if (inCode)
                     {
                         inCode = 0;
                         // The code section is from iCodeStart to i
                         OutBuffer codebuf;

                         codebuf.write(buf->slice().ptr + iCodeStart, i - iCodeStart);
                         codebuf.writeByte(0);

                         // Remove leading indentations from all lines
                         bool lineStart = true;
                         utf8_t *endp = (utf8_t *)codebuf.slice().ptr + codebuf.length();
                         for (utf8_t *p = (utf8_t *)codebuf.slice().ptr; p < endp; )
                         {
                             if (lineStart)
                             {
                                 size_t j = codeIndent;
                                 utf8_t *q = p;
                                 while (j-- > 0 && q < endp && isIndentWS(q))
                                     ++q;
                                 codebuf.remove(p - (utf8_t *)codebuf.slice().ptr, q - p);
                                 assert((utf8_t *)codebuf.slice().ptr <= p);
                                 assert(p < (utf8_t *)codebuf.slice().ptr + codebuf.length());
                                 lineStart = false;
                                 endp = (utf8_t *)codebuf.slice().ptr + codebuf.length(); // update
                                 continue;
                             }
                             if (*p == '\n')
                                 lineStart = true;
                             ++p;
                         }

                         highlightCode2(sc, a, &codebuf, 0);
                         buf->remove(iCodeStart, i - iCodeStart);
                         i = buf->insert(iCodeStart, codebuf.slice().ptr, codebuf.length());
                         i = buf->insert(i, (const char *)")\n", 2);
                         i -= 2; // in next loop, c should be '\n'
                     }
                     else
                     {
                         static const char d_code[] = "$(D_CODE ";

                         inCode = 1;
                         codeIndent = istart - iLineStart;  // save indent count
                         i = buf->insert(i, d_code, strlen(d_code));
                         iCodeStart = i;
                         i--;            // place i on >
                         leadingBlank = true;
                     }
                 }
                 break;

             default:
                 leadingBlank = 0;
                 if (sc->_module->isDocFile || inCode)
                     break;

                 utf8_t *start = (utf8_t *)buf->slice().ptr + i;
                 if (isIdStart(start))
                 {
                     size_t j = skippastident(buf, i);
                     if (i < j)
                     {
                         size_t k = skippastURL(buf, i);
                         if (i < k)
                         {
                             i = k - 1;
                             break;
                         }
                     }
                     else
                         break;
                     size_t len = j - i;

                     // leading '_' means no highlight unless it's a reserved symbol name
                     if (c == '_' &&
                         (i == 0 || !isdigit(*(start - 1))) &&
                         (i == buf->length() - 1 || !isReservedName(start, len)))
                     {
                         buf->remove(i, 1);
                         i = j - 1;
                         break;
                     }
                     if (isIdentifier(a, start, len))
                     {
                         i = buf->bracket(i, "$(DDOC_PSYMBOL ", j, ")") - 1;
                         break;
                     }
                     if (isKeyword(start, len))
                     {
                         i = buf->bracket(i, "$(DDOC_KEYWORD ", j, ")") - 1;
                         break;
                     }
                     if (isFunctionParameter(a, start, len))
                     {
                         //printf("highlighting arg '%s', i = %d, j = %d\n", arg->ident->toChars(), i, j);
                         i = buf->bracket(i, "$(DDOC_PARAM ", j, ")") - 1;
                         break;
                     }

                     i = j - 1;
                 }
                 break;
         }
     }
     if (inCode)
         error(s ? s->loc : Loc(), "unmatched --- in DDoc comment");
 }

 /**************************************************
  * Highlight code for DDOC section.
  */

 void highlightCode(Scope *sc, Dsymbol *s, OutBuffer *buf, size_t offset)
 {
     //printf("highlightCode(s = %s '%s')\n", s->kind(), s->toChars());
     OutBuffer ancbuf;
     emitAnchor(&ancbuf, s, sc);
     buf->insert(offset, (char *)ancbuf.slice().ptr, ancbuf.length());
     offset += ancbuf.length();

     Dsymbols a;
     a.push(s);
     highlightCode(sc, &a, buf, offset);
 }

 /****************************************************
  */

 void highlightCode(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset)
 {
     //printf("highlightCode(a = '%s')\n", a->toChars());

     for (size_t i = offset; i < buf->length(); i++)
     {
         utf8_t c = buf->slice().ptr[i];
         const char *se = sc->_module->escapetable->escapeChar(c);
         if (se)
         {
             size_t len = strlen(se);
             buf->remove(i, 1);
             i = buf->insert(i, se, len);
             i--;                // point to ';'
             continue;
         }

         utf8_t *start = (utf8_t *)buf->slice().ptr + i;
         if (isIdStart(start))
         {
             size_t j = skippastident(buf, i);
             if (i < j)
             {
                 size_t len = j - i;
                 if (isIdentifier(a, start, len))
                 {
                     i = buf->bracket(i, "$(DDOC_PSYMBOL ", j, ")") - 1;
                     continue;
                 }
                 if (isFunctionParameter(a, start, len))
                 {
                     //printf("highlighting arg '%s', i = %d, j = %d\n", arg->ident->toChars(), i, j);
                     i = buf->bracket(i, "$(DDOC_PARAM ", j, ")") - 1;
                     continue;
                 }
                 i = j - 1;
             }
         }
     }
 }

 /****************************************
  */

 void highlightCode3(Scope *sc, OutBuffer *buf, const utf8_t *p, const utf8_t *pend)
 {
     for (; p < pend; p++)
     {
         const char *s = sc->_module->escapetable->escapeChar(*p);
         if (s)
             buf->writestring(s);
         else
             buf->writeByte(*p);
     }
 }

 /**************************************************
  * Highlight code for CODE section.
  */

 void highlightCode2(Scope *sc, Dsymbols *a, OutBuffer *buf, size_t offset)
 {
     unsigned errorsave = global.errors;
     Lexer lex(NULL, (utf8_t *)buf->slice().ptr, 0, buf->length() - 1, 0, 1);
     OutBuffer res;
     const utf8_t *lastp = (utf8_t *)buf->slice().ptr;

     //printf("highlightCode2('%.*s')\n", buf->length() - 1, buf->slice().ptr);
     res.reserve(buf->length());
     while (1)
     {
         Token tok;
         lex.scan(&tok);
         highlightCode3(sc, &res, lastp, tok.ptr);

         const char *highlight = NULL;
         switch (tok.value)
         {
             case TOKidentifier:
             {
                 if (!sc)
                     break;
                 size_t len = lex.p - tok.ptr;
                 if (isIdentifier(a, tok.ptr, len))
                 {
                     highlight = "$(D_PSYMBOL ";
                     break;
                 }
                 if (isFunctionParameter(a, tok.ptr, len))
                 {
                     //printf("highlighting arg '%s', i = %d, j = %d\n", arg->ident->toChars(), i, j);
                     highlight = "$(D_PARAM ";
                     break;
                 }
                 break;
             }
             case TOKcomment:
                 highlight = "$(D_COMMENT ";
                 break;

             case TOKstring:
                 highlight = "$(D_STRING ";
                 break;

             default:
                 if (tok.isKeyword())
                     highlight = "$(D_KEYWORD ";
                 break;
         }
         if (highlight)
         {
             res.writestring(highlight);
             size_t o = res.length();
             highlightCode3(sc, &res, tok.ptr, lex.p);
             if (tok.value == TOKcomment || tok.value == TOKstring)
                 escapeDdocString(&res, o);  // Bugzilla 7656, 7715, and 10519
             res.writeByte(')');
         }
         else
             highlightCode3(sc, &res, tok.ptr, lex.p);
         if (tok.value == TOKeof)
             break;
         lastp = lex.p;
     }
     buf->setsize(offset);
     buf->write(&res);
     global.errors = errorsave;
 }

 /***************************************
  * Find character string to replace c with.
  */

 const char *Escape::escapeChar(unsigned c)
 {
     assert(c < 256);
     //printf("escapeChar('%c') => %p, %p\n", c, strings, strings[c]);
     return strings[c];
 }

 /****************************************
  * Determine if p points to the start of a "..." parameter identifier.
  */

 bool isCVariadicArg(const utf8_t *p, size_t len)
 {
     return len >= 3 && cmp("...", p, 3) == 0;
 }

 /****************************************
  * Determine if p points to the start of an identifier.
  */

 bool isIdStart(const utf8_t *p)
 {
     unsigned c = *p;
     if (isalpha(c) || c == '_')
         return true;
     if (c >= 0x80)
     {
         size_t i = 0;
         if (utf_decodeChar(p, 4, &i, &c))
             return false;   // ignore errors
         if (isUniAlpha(c))
             return true;
     }
     return false;
 }

 /****************************************
  * Determine if p points to the rest of an identifier.
  */

 bool isIdTail(const utf8_t *p)
 {
     unsigned c = *p;
     if (isalnum(c) || c == '_')
         return true;
     if (c >= 0x80)
     {
         size_t i = 0;
         if (utf_decodeChar(p, 4, &i, &c))
             return false;   // ignore errors
         if (isUniAlpha(c))
             return true;
     }
     return false;
 }

 /****************************************
  * Determine if p points to the indentation space.
  */

 bool isIndentWS(const utf8_t *p)
 {
     return (*p == ' ') || (*p == '\t');
 }

 /*****************************************
  * Return number of bytes in UTF character.
  */

 int utfStride(const utf8_t *p)
 {
     unsigned c = *p;
     if (c < 0x80)
         return 1;
     size_t i = 0;
     utf_decodeChar(p, 4, &i, &c);       // ignore errors, but still consume input
     return (int)i;
 }