doc: Comprehensive list of supported commands

[fpelliccioni]

Fixes #676

In the file src/lib/AST/ParseJavadoc.cpp, there are mainly two functions in charge of handling documentation commands:

1. JavadocVisitor::visitInlineCommandComment(...)
   This one mentions inline commands such as: @n, @a, @e, @em, @copybrief, @copydetails, @copydoc, and @ref.

2. JavadocVisitor::visitBlockCommandComment(...)

   • It treats certain block commands in a special manner, for example:
     @brief, @short, @return / @returns / @result, @throw / @throws / @exception, @note, @warning, @par, @li, @details, @see, @pre, @post.
     These commands trigger specific behavior in MrDocs.
   • It does not produce errors but also does nothing with many other commands (e.g., @addindex, @addtogroup, @anchor, @arg, …, @xrefitem).
     Although they are present in the CommandTraits enum and do not cause errors, MrDocs currently does nothing with them.

I have decided to include all these "passively supported" commands in the documentation because:

• Even though MrDocs does nothing concrete with them, they are recognized in the CommandTraits enumeration.
• Some of the "passively supported" commands reference others in the list, creating a chain of mentions.

Additionally, I have made the following documentation adjustments:

• Removed references to other programming languages (Objective-C, Java, etc.). For instance, commands like @category and @protocol (which apply only to Objective-C) were removed. We kept The C programming languages for compatibility and relevance alongside C++. Code, examples and mentions to other programming languages were removed.

• Added the @endlink command, which was commented out in the visitBlockCommandComment(...) switch but referenced by @link. I decided to keep it to cover the @link ... @endlink pair.

• There are open questions about how to handle other points mentioned in the docs:

  • Typical Doxygen configuration options (e.g. CALLER_GRAPH, ENABLED_SECTIONS, etc.).
  • Support for HTML-like syntax (e.g. <em>multiple words</em>) which is referenced in multiple places.
  • The @startuml command, which suggests needing Java and PlantUML. We need to decide if we want to support it.

With this PR, all commands included in the enumeration are now documented, so they can be referenced, even though MrDocs does not yet perform additional processing for some of them.

[cppalliance-bot]

An automated preview of the documentation is available at https://821.mrdocs.prtest2.cppalliance.org/index.html

[alandefreitas]

Even though MrDocs does nothing concrete with them, they are recognized in the CommandTraits enumeration.

So they're unsupported?

Some of the "passively supported" commands reference others in the list, creating a chain of mentions.

So they're supported?

[alandefreitas]

There's already a section for this on the commands page.

The term "commands" for documentation commands might be ambiguous with command line commands.

This could be something like "Documentation Command Reference" but the navtitle would have to be shorter like "Documentation Commands" or something,

[alandefreitas]

This page is kind of boring and ugly.

Commands could be on a table like the ones mrdocs generates where the first column has the command and the second column has a brief description.

To make it less repetitive, commands can be put into subsections categories. The basic categories are block and inline commands. Then there's subcategories based on what the command does.

Each section can have a small paragraph explaining the table to come.

The command text should be as wrapped in "`"s.

Unsupported commands can be in red without a page so that users and developers can keep track of them.

Unimplemented commands are unsupported commands.

[alandefreitas]

We don't need that (the nav is more visible already). The one that already exists also needs to be removed.

[alandefreitas]

That's markdown. Not asciidoctor.

[alandefreitas]

All supported commands need examples.

[alandefreitas]

No point in describing unsupported commands.

[alandefreitas]

That's not imperfect. It's 100% unsupported.

[alandefreitas]

Please don't tell me you're copy/pasting these from doxygen's documentation.