copperspice / doxypress

Documentation generator using annotated sources for multiple computer languages
https://www.copperspice.com/
GNU General Public License v2.0
150 stars 14 forks source link

Doxypress hangs on comments with backticks #34

Closed rleh closed 4 years ago

rleh commented 4 years ago

Comments in C++ files with backticks (see below) hang the parser.

Steps to reproduce

Create an empty directory with a *.hpp or *.cpp (other file extensions not tested) file

/// `text`

Create a (default) doxypress.json file

doxypress.json
{
    "clang": {
        "clang-compilation-path": "",
        "clang-dialect": "-std=c++14",
        "clang-flags": [
            ""
        ],
        "clang-parsing": false,
        "clang-use-headers": true
    },
    "configuration": {
        "allow-sub-grouping": true,
        "allow-unicode-names": false,
        "always-detailed-sec": false,
        "auto-link": true,
        "brief-member-desc": true,
        "built-in-stl-support": false,
        "case-sensitive-fname": true,
        "cpp-cli-support": false,
        "create-subdirs": false,
        "duplicate-docs": false,
        "enabled-sections": [
            ""
        ],
        "extract-all": false,
        "extract-anon-namespaces": false,
        "extract-local-classes": true,
        "extract-local-methods": false,
        "extract-package": false,
        "extract-private": false,
        "extract-static": false,
        "file-version-filter": "",
        "force-local-includes": false,
        "full-path-names": true,
        "generate-bug-list": true,
        "generate-deprecate-list": true,
        "generate-test-list": true,
        "generate-todo-list": true,
        "group-nested-compounds": false,
        "hide-compound-ref": false,
        "hide-friend-compounds": false,
        "hide-in-body-docs": false,
        "hide-navtree-members": false,
        "hide-scope-names": false,
        "hide-undoc-classes": false,
        "hide-undoc-members": false,
        "idl-support": true,
        "inherit-docs": true,
        "inline-grouped-classes": false,
        "inline-info": true,
        "inline-inherited-member": false,
        "inline-simple-struct": false,
        "internal-docs": false,
        "javadoc-auto-brief": false,
        "language-mapping": [
            ""
        ],
        "layout-file": "",
        "main-page-name": "",
        "main-page-omit": false,
        "markdown": true,
        "max-init-lines": 30,
        "multiline-cpp-brief": false,
        "ns-alias": [
            ""
        ],
        "qt-auto-brief": false,
        "repeat-brief": true,
        "separate-member-pages": false,
        "short-names": false,
        "show-file-page": true,
        "show-grouped-members-inc": false,
        "show-include-files": true,
        "show-namespace-page": true,
        "show-used-files": true,
        "sip-support": false,
        "sort-brief-docs": false,
        "sort-by-scope-name": false,
        "sort-class-case-sensitive": false,
        "sort-constructors-first": false,
        "sort-group-names": false,
        "sort-member-docs": true,
        "strict-sig-matching": false,
        "tcl-subst": [
            ""
        ],
        "toc-include-headers": 0,
        "use-typedef-name": false
    },
    "dot": {
        "class-diagrams": true,
        "dia-file-dirs": [
            ""
        ],
        "dia-path": "",
        "directory-graph": true,
        "dot-call": false,
        "dot-called-by": false,
        "dot-class-graph": true,
        "dot-cleanup": true,
        "dot-collaboration": true,
        "dot-file-dirs": [
            ""
        ],
        "dot-font-name": "Helvetica",
        "dot-font-path": "",
        "dot-font-size": 10,
        "dot-graph-max-depth": 0,
        "dot-graph-max-nodes": 50,
        "dot-hierarchy": true,
        "dot-image-format": "png",
        "dot-include": true,
        "dot-included-by": true,
        "dot-multiple-targets": false,
        "dot-num-threads": 0,
        "dot-path": "",
        "dot-transparent": false,
        "generate-legend": true,
        "group-graphs": true,
        "have-dot": false,
        "hide-undoc-relations": true,
        "interactive-svg": false,
        "msc-file-dirs": [
            ""
        ],
        "mscgen-path": "",
        "plantuml-cfg-file": "",
        "plantuml-inc-path": [
            ""
        ],
        "plantuml-jar-path": "",
        "template-relations": false,
        "uml-limit-num-fields": 10,
        "uml-look": false
    },
    "doxypress-format": 1,
    "doxypress-updated": "2018-Jun-30",
    "external": {
        "all-externals": false,
        "external-groups": true,
        "external-pages": true,
        "generate-tagfile": "",
        "perl-path": "/usr/bin/perl",
        "tag-files": [
            ""
        ]
    },
    "general": {
        "abbreviate-brief": [
            "The $name class",
            "The $name widget",
            "The $name file",
            "is",
            "provides",
            "specifies",
            "contains",
            "represents",
            "a",
            "an",
            "the"
        ],
        "aliases": [
            ""
        ],
        "lookup-cache-size": 0,
        "optimize-c": false,
        "optimize-cplus": true,
        "optimize-fortran": false,
        "optimize-java": false,
        "optimize-python": false,
        "output-dir": "",
        "output-language": "English",
        "strip-from-inc-path": [
            ""
        ],
        "strip-from-path": [
            ""
        ],
        "tab-size": 4
    },
    "index": {
        "alpha-index": true,
        "cols-in-index": 5,
        "ignore-prefix": [
            ""
        ]
    },
    "input": {
        "example-patterns": [
            "*"
        ],
        "example-recursive": false,
        "example-source": [
            ""
        ],
        "exclude-files": [
            ""
        ],
        "exclude-patterns": [
            ""
        ],
        "exclude-symbols": [
            ""
        ],
        "exclude-symlinks": false,
        "filter-patterns": [
            ""
        ],
        "filter-program": "",
        "filter-source-files": false,
        "filter-source-patterns": [
            ""
        ],
        "image-path": [
            ""
        ],
        "input-encoding": "UTF-8",
        "input-patterns": [
            "*.as",
            "*.c",
            "*.cc",
            "*.cpp",
            "*.cxx",
            "*.c++",
            "*.cs",
            "*.d",
            "*.ddl",
            "*.dox",
            "*.for",
            "*.f",
            "*.f90",
            "*.h",
            "*.hh",
            "*.hxx",
            "*.hpp",
            "*.h++",
            "*.idl",
            "*.ii",
            "*.ixx",
            "*.ipp",
            "*.i++",
            "*.inc",
            "*.inl",
            "*.java",
            "*.js",
            "*.m",
            "*.md",
            "*.mm",
            "*.markdown",
            "*.odl",
            "*.php",
            "*.php3",
            "*.php4",
            "*.php5",
            "*.phtml",
            "*.py",
            "*.pyw",
            "*.qsf",
            "*.tcl",
            "*.ucf"
        ],
        "input-recursive": false,
        "input-source": [
            ""
        ],
        "mdfile-mainpage": ""
    },
    "messages": {
        "quiet": false,
        "warn-doc-error": true,
        "warn-format": "$file:$line: $text",
        "warn-logfile": "",
        "warn-undoc": true,
        "warn-undoc-param": false,
        "warnings": true
    },
    "output-chm": {
        "binary-toc": false,
        "chm-file": "",
        "chm-index-encoding": "",
        "generate-chi": false,
        "generate-chm": false,
        "hhc-location": "",
        "toc-expanded": false
    },
    "output-docbook": {
        "docbook-output": "docbook",
        "docbook-program-listing": false,
        "generate-docbook": false
    },
    "output-docset": {
        "docset-bundle-id": "org.doxypress.Project",
        "docset-feedname": "DoxyPress generated docs",
        "docset-publisher-id": "org.doxypress.Publisher",
        "docset-publisher-name": "Publisher",
        "generate-docset": false
    },
    "output-eclipse": {
        "eclipse-doc-id": "org.doxypress.Project",
        "generate-eclipse": false
    },
    "output-html": {
        "disable-index": false,
        "enum-values-per-line": 4,
        "external-links-in-window": false,
        "formula-fontsize": 10,
        "formula-transparent": true,
        "generate-html": true,
        "generate-treeview": false,
        "ghostscript": "",
        "html-colorstyle-gamma": 80,
        "html-colorstyle-hue": 220,
        "html-colorstyle-sat": 100,
        "html-dynamic-sections": false,
        "html-extra-files": [
            ""
        ],
        "html-file-extension": ".html",
        "html-footer": "",
        "html-header": "",
        "html-index-num-entries": 100,
        "html-output": "html",
        "html-search": false,
        "html-stylesheets": [
            ""
        ],
        "html-timestamp": true,
        "mathjax-codefile": "",
        "mathjax-extensions": [
            ""
        ],
        "mathjax-format": "HTML-CSS",
        "mathjax-relpath": "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/",
        "search-data-file": "searchdata.xml",
        "search-external": false,
        "search-external-id": "",
        "search-external-url": "",
        "search-mappings": [
            ""
        ],
        "search-server-based": false,
        "treeview-width": 250,
        "use-mathjax": false
    },
    "output-latex": {
        "cite-bib-files": [
            ""
        ],
        "generate-latex": false,
        "latex-batch-mode": false,
        "latex-bib-style": "plain",
        "latex-cmd-name": "latex",
        "latex-compact": false,
        "latex-extra-files": [
            ""
        ],
        "latex-extra-packages": [
            ""
        ],
        "latex-footer": "",
        "latex-header": "",
        "latex-hide-indices": false,
        "latex-hyper-pdf": true,
        "latex-output": "latex",
        "latex-paper-type": "a4",
        "latex-pdf": true,
        "latex-ps": true,
        "latex-source-code": false,
        "latex-stylesheets": [
            ""
        ],
        "latex-timestamp": false,
        "make-index-cmd-name": "makeindex"
    },
    "output-man": {
        "generate-man": false,
        "man-extension": ".3",
        "man-links": false,
        "man-output": "man",
        "man-subdir": ""
    },
    "output-perl": {
        "generate-perl": false,
        "perl-latex": false,
        "perl-prefix": "",
        "perl-pretty": true
    },
    "output-qhelp": {
        "generate-qthelp": false,
        "qch-file": "",
        "qhp-cust-attrib": [
            ""
        ],
        "qhp-cust-filter-name": "",
        "qhp-namespace": "org.doxypress.Project",
        "qhp-sect-attrib": [
            ""
        ],
        "qhp-virtual-folder": "doc",
        "qthelp-gen-path": ""
    },
    "output-rtf": {
        "generate-rtf": false,
        "rtf-compact": false,
        "rtf-extension": "",
        "rtf-hyperlinks": false,
        "rtf-output": "rtf",
        "rtf-paper-type": "a4",
        "rtf-source-code": false,
        "rtf-stylesheet": ""
    },
    "output-xml": {
        "generate-xml": false,
        "xml-output": "xml",
        "xml-program-listing": true
    },
    "preprocessor": {
        "enable-preprocessing": true,
        "expand-as-defined": [
            ""
        ],
        "expand-only-predefined": false,
        "include-path": [
            ""
        ],
        "include-patterns": [
            ""
        ],
        "macro-expansion": false,
        "predefined-macros": [
            ""
        ],
        "search-includes": true,
        "skip-function-macros": true
    },
    "project": {
        "project-brief": "",
        "project-logo": "",
        "project-name": "My Project",
        "project-version": ""
    },
    "source": {
        "inline-source": false,
        "ref-by-relation": false,
        "ref-link-source": true,
        "ref-relation": false,
        "source-code": false,
        "source-tooltips": true,
        "strip-code-comments": true,
        "suffix-exclude-navtree": [
            "doc",
            "dox",
            "md",
            "markdown",
            "txt"
        ],
        "suffix-header-navtree": [
            "h",
            "hh",
            "hxx",
            "hpp",
            "h++",
            "idl",
            "ddl",
            "pidl"
        ],
        "suffix-source-navtree": [
            "c",
            "cc",
            "cxx",
            "cpp",
            "c++",
            "ii",
            "ixx",
            "ipp",
            "i++",
            "inl",
            "java",
            "m",
            "mm",
            "xml"
        ],
        "use-htags": false,
        "verbatim-headers": true
    }
}

Run doxypress

$ # optional with debug all flags
$ doxypress -d classes -d commentcnv -d commentscan -d extcmd -d filteroutput -d findmembers -d functions -d lex -d markdown -d preprocessor -d printtree -d validate -d variables

DoxyPress Version: 1.3.6

**  Read Project Configuration
**  Verify Project Configuration

Initialization
Parse input files
Searching for include files
Searching for example files
Searching for images
Searching for dot files
Searching for msc files
Searching for dia files
Searching for files to exclude
Searching for files to process
Searching for files in directory /xyz
Parse tag files

**  Parsing
Processing /xyz/a.cpp
Entering lexical analyzer: src/generated/pre.cpp (for: /xyz/a.cpp)
Finished lexical analyzer: src/generated/pre.cpp (for: /xyz/a.cpp)
Entering lexical analyzer: src/generated/commentcnv.cpp (for: /xyz/a.cpp)
Entering lexical analyzer: src/generated/parse_cstyle.cpp (for: /xyz/a.cpp)

# hangs forever
^C
Cleaning up
DoxyPress aborted
$ 

Doxypress Version

$ doxypress --version
DoxyPress Version: 1.3.6
email: info@copperspice.com

Downloaded from https://download.copperspice.com/

System: Linux, Fedora 31

rleh commented 4 years ago

Running in GDB leads to the following findings:

gdb doxypress
# ...
(gdb) info stack
#0  0x0000000000495206 in QString8::const_iterator::const_iterator(CsString::CsStringIterator<CsString::utf8, std::allocator<unsigned char> >) ()
#1  0x00000000004953ab in QString8::const_iterator::operator-(long) const ()
#2  0x0000000000887373 in findEndOfLine(QString8&, Cs::QStringView<QString8>, QString8::const_iterator&, QString8::const_iterator&, QString8::const_iterator&) ()
#3  0x00000000008881d0 in processQuotations(Cs::QStringView<QString8>, int) ()
#4  0x000000000088a0e4 in processMarkdown(QString8 const&, int, QSharedPointer<Entry>, QString8 const&) ()
#5  0x00000000009c5778 in parseCommentBlock(ParserInterface*, QSharedPointer<Entry>, QString8 const&, QString8 const&, int&, bool, bool, bool, Protection&, int&, bool&) ()
#6  0x0000000000a25960 in handleCommentBlock(QString8 const&, bool) ()
#7  0x0000000000a18b58 in parse_cstyle_YYlex() ()
#8  0x0000000000a26c6a in parseMain(QString8 const&, QString8 const&, QStringList&, QSharedPointer<Entry>) ()
#9  0x0000000000a273dc in CPP_Parser::parseInput(QString8 const&, QString8 const&, QSharedPointer<Entry>, ParserMode, QStringList&, bool) ()
#10 0x000000000048dd4b in Doxy_Work::parseFile(ParserInterface*, QSharedPointer<Entry>, QSharedPointer<FileDef>, QString8, ParserMode, QStringList&) ()
#11 0x000000000048e962 in Doxy_Work::parseFiles(QSharedPointer<Entry>) ()
#12 0x000000000043861b in processFiles() ()
#13 0x0000000000778527 in main ()

Doxypress seems to get stuck in findEndOfLine(...) in processQuotations(...) in processMarkdown(...), only the first (here: two) stack entry change.

agserm commented 4 years ago

Thank you. Detailed reports like this one are very helpful.

It turns out this issue was reported recently and resolved with commit e0ffdbf. We anticipate making the next binary release around the end of the month. If you need something sooner and cannot build from master, let us know.

rleh commented 4 years ago

Thank you for your quick reply.

The modm toolbox is going to replace doxygen for is API documentation with doxypress, but that's not time-sensitive.