> 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
Re: [Development] Proposal to retain \since version information in Qt Documentation
Paul Wicking via Development Wed, 25 Sep 2024 12:22:52 -0700
- Re: [Development] Proposal to reta... Axel Spoerl via Development
- Re: [Development] Proposal to ... Thiago Macieira
- Re: [Development] Proposal... Jaroslaw Kobus via Development
- Re: [Development] Prop... Thiago Macieira
- Re: [Development]... Jaroslaw Kobus via Development
- Re: [Development] Proposal... Paul Wicking via Development
- Re: [Development] Proposal to ... Paul Wicking via Development
- Re: [Development] Proposal to ... Paul Wicking via Development
- Re: [Development] Proposal... Axel Spoerl via Development
- Re: [Development] Prop... Jerome Pasion via Development
- Re: [Development] Proposal to reta... Paul Wicking via Development
- Re: [Development] Proposal to reta... Mathias Hasselmann via Development
- Re: [Development] Proposal to retain \s... Jason McDonald
- Re: [Development] Proposal to retain \s... Volker Hilsheimer via Development