search

mosra / m.css

A no-nonsense, no-JavaScript CSS framework, site and documentation theme for content-oriented websites
https://mcss.mosra.cz
Other
409 stars 92 forks source link

Assert on Doxygen 1.9 complaining about Doxygen 1.8 bugs instead of graceful handling #177

Closed biziosan closed 2 years ago

biziosan commented 4 years ago

Hi,

I am getting the following exception when I try to process my code with Doxygen 1.9:

Traceback (most recent call last):
  File "/opt/tools/mcss/documentation/doxygen.py", line 3853, in <module>
    run(state, templates=os.path.abspath(args.templates), wildcard=args.wildcard, index_pages=args.index_pages, search_merge_subtrees=not args.search_no_subtree_merging, search_add_lookahead_barriers=not args.search_no_lookahead_barriers, search_merge_prefixes=not args.search_no_prefix_merging)
  File "/opt/tools/mcss/documentation/doxygen.py", line 3684, in run
    extract_metadata(state, file)
  File "/opt/tools/mcss/documentation/doxygen.py", line 2215, in extract_metadata
    compound.brief = parse_desc(state, compounddef.find('briefdescription'))
  File "/opt/tools/mcss/documentation/doxygen.py", line 1702, in parse_desc
    parsed = parse_desc_internal(state, element)
  File "/opt/tools/mcss/documentation/doxygen.py", line 1683, in parse_desc_internal
    assert not has_block_elements and paragraph_count <= 1, \
AssertionError: : brief description containing multiple paragraphs, possibly due to @ingroup following a @brief in <blockquote><p>Generic base configuration to use when no other configuration is needed.</p></blockquote>. This was a bug in Doxygen 1.8.15/16 and fixed since, please upgrade.

Is there a way to know what class generated the exception and if this is a bug?

mosra commented 4 years ago

Hi, if you run with --verbose it should show what file it processed right before. And the Generic base configuration to use when no other configuration is needed. is the piece of input it failed on, I think.

There's Doxygen 1.9 already? Huh. I'm frightened to discover what exciting new bugs it has, ha.

biziosan commented 4 years ago

There's Doxygen 1.9 already? Huh. I'm frightened to discover what exciting new bugs it has, ha.

I know, right, LOL? Also, I don't understand why we can't have a more modern documentation system for C++... anyway...

The --debug flag did the trick. I have attached the file if it helps.

DEBUG:root:Extracting metadata from classeye_1_1configuration_1_1GenericConfiguration.xml
Traceback (most recent call last):
  File "/opt/tools/mcss/documentation/doxygen.py", line 3853, in <module>
    run(state, templates=os.path.abspath(args.templates), wildcard=args.wildcard, index_pages=args.index_pages, search_merge_subtrees=not args.search_no_subtree_merging, search_add_lookahead_barriers=not args.search_no_lookahead_barriers, search_merge_prefixes=not args.search_no_prefix_merging)
  File "/opt/tools/mcss/documentation/doxygen.py", line 3684, in run
    extract_metadata(state, file)
  File "/opt/tools/mcss/documentation/doxygen.py", line 2215, in extract_metadata
    compound.brief = parse_desc(state, compounddef.find('briefdescription'))
  File "/opt/tools/mcss/documentation/doxygen.py", line 1702, in parse_desc
    parsed = parse_desc_internal(state, element)
  File "/opt/tools/mcss/documentation/doxygen.py", line 1683, in parse_desc_internal
    assert not has_block_elements and paragraph_count <= 1, \
AssertionError: : brief description containing multiple paragraphs, possibly due to @ingroup following a @brief in <blockquote><p>Generic base configuration to use when no other configuration is needed.</p></blockquote>. This was a bug in Doxygen 1.8.15/16 and fixed since, please upgrade.

By the way, I tired all other Doxygen versions and the problem remains. Is there a way around this?

classeye_1_1configuration_1_1GenericConfiguration.xml.zip

mosra commented 4 years ago

Is there a way around this?

There should be -- what exactly does the input markup look like for the GenericConfiguration class? Maybe it's just some indentation or extra characters throwing Doxygen off.

biziosan commented 4 years ago 
    ///> Types of user streams
    class stream_types_e : public basic::types::EnumClass<stream_types_e>
    {
...
    };

Replacing it with:

    /**
     * Types of user streams.
     */
    class stream_types_e : public basic::types::EnumClass<stream_types_e>
    {
...
    };

seems to solve the problem. I am running m.css to find all these occurrences and fix them. Shouldn't this be acceptable?

mosra commented 4 years ago

Ah, yep. The > is a markdown syntax for a blockquote, and that makes no sense to have in a single-line brief docs. (Contrary to ///<, which is a Doxygen syntax for describing a symbol preceding the comment. Sigh, syntax clashes.)

That said, the tool shouldn't crash on that -- I'll see what can be done to handle this more gracefully. However (as you can judge from the sheer amount of pending issues on this repo) right now I don't have much time, so hope it's fine with you if this issue stays open for a while? :)

biziosan commented 4 years ago

No problem! I am working around the problem in this way. Thank you for giving us a more modern feel for my C++ projects!!

biziosan commented 4 years ago

I fixed all the definitions with the same problem and I got to the bottom of the conversion without exceptions!

However, the index.html is empty though. This is another issue I think.

mosra commented 4 years ago

Do you have a @mainpage defined somewhere? If not, it'll produce an empty page with only the top navbar.

Regarding the main page, it should be pretty similar to the vanilla HTML output, so if you get something there you should get it here also.

biziosan commented 4 years ago

Sorry to bother you with this! Thank you to be so responsive!

I do not have a @mainpage.

However, in Doxygen the list of namespaces and classes is there... I can see everything.

In MCSS there is no namespace nor classes or files. I know that the files are there. I can see them and if I open one and navigate through the classes just fine (no class diagrams though).

mosra commented 4 years ago

Huh, I'm not sure I understand ... can you post a screenshot of the index page? At the very least there should be a navbar on top, leading to class, namespace and file list, and the lists having all your APIs. Like here, for example (except for the page contents, of course): https://doc.magnum.graphics/magnum/

Class diagrams are deliberately not supported, although that might change at some point.

Since it's not really related to the original issue, possibly a better place to discuss this would be the Gitter chat room -- https://gitter.im/mosra/m.css . Simply log in with your GitHub account.

biziosan commented 4 years ago

Absolutely! I am going there now. Thank you!

allebacco commented 4 years ago

Even for me, with Doxygen 1.8.20 the pages with the list of namespaces and the list of classes are empty. However, the html pages for each class and namespace have been generated, because they are present on disk.

mosra commented 4 years ago

@allebacco this is an unfortunate consequence of how much mess is there in Doxygen's XML output -- because it's not clear what is useful and what not, the documentation generator implicitly includes only what has at least some documentation. Please see the troubleshooting section in the docs. A related issue discussing this recently is also #183.

mosra commented 2 years ago

(Sorry for embarrassingly late replies, finally got back to this project and to the final boss that is Doxygen.)

The assertion with the confusing message got reverted in 92b6a005d3c6a3599c995c0be4c268404cecacc7, and buggy handling of ///> by Doxygen got worked around in 1f969feffef7b76bda5ec30d35c5e8a1f0a23982 together with a regression test case. That's everything there is to fix the original cause for this issue I think.