Re: [Development] Proposal to retain \since version information in Qt Documentation

[Paul Wicking via Development]

> On 24 Sep 2024, at 19:24, Christian Ehrlicher via Development 
> <development@qt-project.org> wrote:
> 
> You're aware that noone will see those \since tags in any documentation 
> except he builds it by himself (which even I did not manage until now for 
> unknown reasons - maybe because I try to build the documentation for qtbase 
> only - don't know) and also needs to modify config.qdocconf before?
> So basically we're leaving in code which is ifdef'd out aka dead code.
> Maybe we should focus on improving the documentation instead discussing if 
> (or if not) we remove dead code added 20 years ago.
> 

Hi Christian,

Thank you for your response and for sharing your perspective.

I understand that it might seem like the `\since` tags are effectively
"dead code" because they are not currently visible in the online documentation
at doc.qt.io. However, I'd like to clarify that in the patches I've reviewed,
the `\since` annotations are not actually conditionally compiled out or
`#ifdef`'ed out in the source code. They remain active within the documentation
comments and are processed by QDoc. 

The visibility of the `\since` information in the generated documentation is
controlled by the `ignoresince` configuration variable in QDoc. By adjusting
this single variable in the `.qdocconf` file, we can enable or disable the
display of `\since` annotations across all modules without modifying hundreds of
source files. This flexibility means that the `\since` tags are not dead code;
they're dormant information that can be easily reactivated when needed.

Retaining the `\since` annotations keeps open the possibility of displaying this
valuable historical information in the online documentation with minimal
effort. It avoids the need to edit numerous files across multiple modules if we
decide to make this information visible in the future.

Regarding your point about focusing on improving the documentation instead of
discussing the removal of "dead code," I believe that preserving the `\since`
annotations contributes to the overall quality and completeness of our
documentation. It provides context and aids developers who might need this
historical information for various reasons, as previously discussed.

On a side note, I'm sorry to hear that you've encountered difficulties building
the documentation locally, especially for `qtbase`. If you'd like, I'd be more
than happy to help you troubleshoot the issue or guide you through the
process. Please feel free to reach out, and we can work on it together.

Once again, I appreciate your engagement in this discussion. I think it's
important that we consider all viewpoints to make decisions that best support
the Qt community as a whole.

Kind regards,

Paul Wicking
Staff Software Engineer
Qt Group

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development