diseraluca wrote:

This might be a breaking change, so I'm not sure if it will be
possible to merge it, but I would like to give some context on where
the change is coming from.

I'm trying (in my position as an employee of The Qt Company), to
migrate our documentation generation tool, QDoc, which depends on both
of Clang's C and C++ APIs, and similarly our CI systems, to support
LLVM 16 and 17 to catch up with the current releases.

Due to a bug fix that happened between 15 and 16, our product behaves
differently on the two versions, and we are using
to stabilize the software behavior on pre-16 and post-16 LLVM
releases, which is the suggested migration path
( https://github.com/llvm/llvm-project/issues/61810 ,
https://github.com/llvm/llvm-project/issues/58040 ).

Using those functions has been generally working for us, but the
behavior that I'm changing in this patch has been a blocker.

As a documentation generation tool we generally require a certain
consistency between generations of different version of the same
codebase, unless something in the code changed so that it justifies
the changes in the documentation itself.

Due to Qt's codebase being quite convoluted, we don't really have too
much control about the order that certain specializations will be
encountered in, albeit we could do some trick to try and control that
from QDoc.

Nonetheless, we are generally required to have the output be stable
when the documented code is not meaningfully changed between release
sets of our documentation.

Having the produced output change because of the first encountered
specialization changing in the codebase is not feasible, as it break
this desiderable property of a documentation set and may break our
regression-testing suite that is enforced in CI.

Furthermore, the chosen specialization may produce incorrect
information, which we cannot show to the end user of the documentation

For example, we currently have `QFuture` define a `const_iterator`
alias that is later used as the argument or return type of some of our
documented callables.

Due to the way the current codebase is set up, the chosen
specialization is `QFuture<void>` so that, for example,
`QFuture::constBegin()` would be shown to the user as returning a
Nonetheless, `QFuture<void>` is the only specialization that cannot
have a `const_iterator` and, as a consequence, doesn't have a
`constBegin` method in the first place.

It is obviously impossible to have this change in 16/17.
My current plan is to maintain our own implementation of
but would prefer to be able to converge back when we can consider 18
the minimum version needed for QDoc, quite far in the future.

I further generally think that a more stable output is a preferred
property for this type of computations considering the possible
usages, such that the lack of the current behavior is either a better
default or a non-meaningful change in many expected usages.

cfe-commits mailing list

Reply via email to