Remove "**TODO**"

[Meakk]

Hi!
I'm trying to generate markdown files from doxygen and tried this tool.
While I like the output, there are a lot a **TODO** occurence appearing in the md files like this one:

**TODO**:

* qualifiedname {"type":"element","name":"qualifiedname","attributes":{},"children":[{"type":"text","text":"f3d::camera::setPosition"}]}

What does it mean? Is it safe to ignore? If yes, is there an option to remove them?

[Meakk]

@fredericbonnet I'm happy to submit a PR to add an argument to the CLI to skip listing the TODO, but I'd like pointers as I'm not familiar with the code base at the moment.

[fredericbonnet]

Hi and sorry for the late reply! The TODOs are placeholders in XML elements that don't have explicit rendering, adding them is trivial for the simplest ones (strings, paragraphs, etc). Do you have a list of those TODOs? Adding an option to skip those is a good idea, however not sure it's easy to do given how the renderer works but I'll take a look.

[Meakk]

Hello!

Yes, we have the 3 missing elements: qualifiedname, includes and templateparamlist.
Here are some examples:

* qualifiedname {"type":"element","name":"qualifiedname","attributes":{},"children":[{"type":"text","text":"f3d::camera::setPosition"}]}

* includes {"type":"element","name":"includes","attributes":{"local":"no","refid":"camera_8h"},"children":[{"type":"text","text":"camera.h"}]}

* templateparamlist {"type":"element","name":"templateparamlist","attributes":{},"children":[{"type":"text","text":"\n          "},{"type":"element","name":"param","attributes":{},"children":[{"type":"text","text":"\n            "},{"type":"element","name":"type","attributes":{},"children":[{"type":"text","text":"typename..."}]},{"type":"text","text":"\n            "},{"type":"element","name":"declname","attributes":{},"children":[{"type":"text","text":"Args"}]},{"type":"text","text":"\n            "},{"type":"element","name":"defname","attributes":{},"children":[{"type":"text","text":"Args"}]},{"type":"text","text":"\n          "}]},{"type":"text","text":"\n        "}]}

We ran into other issues we end up patching with a post-process step here: https://github.com/f3d-app/f3d-website/blob/6fa50dafa856f5b8d73f059f8d2cd191ae13b5ff/tools/generateDocumentation.ts#L85
Another issue we couldn't fix is the order of the lines in files like class_contents.md that change at every run.

Other than that, it works quite well and you can see it live here: https://f3d.app/docs/next/category/libf3d-api-reference
So thanks a lot this!

[fredericbonnet]

@Meakk I've released a new version 0.6.5 that fixes the following issues:

• Hide TODO sections by default and add showTodos configuration option
• Fix bad links with undefined refids (=> the issue with undefined.md links)
• Fix compound index ordering

The first two means you can remove those postprocessing steps. The last one will ensure the index order remains the same between run.

BTW don't hesitate to suggest enhancements if you think something's missing from the output! I'm primary using it for C projects, which means a lot of C++ attributes might not be supported.

[Meakk]

Thank you @fredericbonnet, I confirm the TODOs are commented out now.
It looks like there is no undefined.md anymore too.

Here are additional things:

• I think there's a bug in seaborg, classes with an _ in the name have an additional backslash added: <compoundname>f3d::mesh_t</compoundname> translates to # Structure f3d::mesh\_t

• Docusaurus removes anchors of h1 levels because technically it appears a single time at the top level of the document, so links to this anchor fail. I think seaborg should omit links like namespacef3d.md#namespacef3d and should just point to the document namespacef3d.md without anchor if possible

• The file_contents.md is still giving different ordering at every seaborg run. It should be consistent at least, or better alphabetically sorted. Same thing for struct_contents.md and class_contents.md

• Badges list at the end of the documents are also randomly sorted.