Add a requirements section to usage.adoc

[gennaroprota]

[cppalliance-bot]

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

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2025-10-03 16:27:15 UTC

[alandefreitas]

Isn't that information like everywhere in the documentation over and over again already?

[gennaroprota]

@vinniefalco wanted an explicit statement about the IFNDR case.

[alandefreitas]

@vinniefalco That's the pattern I was attempting to communicate earlier today, which also just happened in #1048 and many others: a design discussion about problem X, where solution Y is proposed, is (reasonably) interpreted as an order to implement Y regardless of X.

The issues and PRs don't even bother to mention what problem X they're attempting to solve, and any attempt to even understand what's happening is futile because "Vinnie told me so" is, to be fair, a somewhat reasonable answer.

[vinniefalco]

The motivation for this change is the need to fully explain to the user what the requirements are for the input program. It has to compile with latest clang. It has to be well-formed, and in particular we require that symbols with the same name have the identical declarations. Unfortunately, it is possible to create a program where the same type has different declarations in different files and still get it to compile and link, without a diagnostic. And in some cases this could be valid C++ (or close to it). Yet for Mr. Docs it is catastrophic because of how we merge things from different translation units into the same corpus data structure.

This needs to be explained to the user, so when someone has a problem we can point them to the docs and say "does your program meet these requirements."

[alandefreitas]

I completely agree the requirements should be clear to user. It's extremely important for users to understand this difference from doxygen as soon as possible. In fact, this content should probably move to the beginning of this page or be exposed much sooner.

However, the problem I was previously mentioning with this issue is not the that requirements should not be listed. The problems I mentioned were:

1. The form the section is included in the page: In this particular issue is the requirement list has a single requirement and this very page already includes a gigantic section about this requirement. This PR completely ignores what already exists. The gigantic section is already explaining not only this requirement but also includes all common strategies in MrDocs to deal with it. At the very least, the new content should make sense in the context of the content that already exists and not be some copy/paste section content completely unrelated to the flow of the text. Otherwise, we have two sequent sections talking about the same thing.
2. And then the more general recurring problem of these "because-vinnie-told-me-so" issues and PR that are impossible to review, but I'm not going to be repetitive here because I believe we're already working on this problem in parallel.

[vinniefalco]

If there is already exposition describing the requirements on the input requirements, then any additional exposition should obviously be placed there

[gennaroprota]

this very page already includes a gigantic section about this requirement.

@alandefreitas: Sorry, Alan. I'm a bit confused. Which section are you hinting at? I see no "gigantic" section at all in usage.adoc.

[alandefreitas]

@gennaroprota Hi! Sorry about that.

Thank you for your work on this PR. In the other comment, I was previously concerned about a parallel social issue related to the process by which these issues and PRs are being created. This complaint is unrelated to your work on this individual PR, and I forgot to make that clear. I'm sorry.

Regarding this PR, the following section not only mentions that MrDocs only works with valid C++ code but also covers many variations of this theme. For instance, that's how the very next section starts:

== Extracting Documentation

Unlike other documentation generators, MrDocs only works with valid {cpp} code.

So the very first sentence touches on this theme. Of course, "IFNDR" code is more specific than "valid/invalid" code, but you see where I'm going with this. "IFNDR" could be used there just as well, and the new section would break the flow of the text. It's just out of place, considering how the previous and following sections are structured.

To be clear, I believe none of that is your fault, and you're welcome to disregard this comment. I don't think that's a serious problem. If you'd like, I can merge this as is. Just let me know.