<table><tr><td style="">kossebau created this revision.<br />kossebau added subscribers: Frameworks, KDevelop, ochurlaud.
</td><a style="text-decoration: none; padding: 4px 8px; margin: 0 8px 8px; float: right; color: #464C5C; font-weight: bold; border-radius: 3px; background-color: #F7F7F9; background-image: linear-gradient(to bottom,#fff,#f1f0f1); display: inline-block; border: 1px solid rgba(71,87,120,.2);" href="https://phabricator.kde.org/D2854" rel="noreferrer">View Revision</a></tr></table><br /><div><strong>REVISION SUMMARY</strong><div><p>To enable creation of qch files during a normal build, <br />
for documenting the public API of a lib.<br />
These macros are especially done with release builds in mind,<br />
so distributed packages (like from Linux distributions) can<br />
include qch files matching the version of the library and will be<br />
also automatically updated on new versions of the libary.</p>

<p>Next to that the macros also supports linking between different<br />
qch files, so a subclass from another library for which there also<br />
is a qch file installed will be linked to the entry in that other<br />
qch file.</p>

<p>This should be a nice addition to the online service like api.kde.org,<br />
like qassitent/qt qhc files are to doc.qt.io</p>

<p>Open questions:<br />
a) recommended install path for qch and tag files?<br />
What would KDevelop & Co. like for easy automatic discovery of qch files?<br />
What would be a nice var name for such dirs to be used with KDEInstallDirs?</p>

<p>b) best way to specify sources to use for created API docs?<br />
SOURCE_DIRS in this draft is the only option to specify the input to<br />
doxygen, following the inspiration of kde-dev-scripts/kdedoxyqt.sh.<br />
Being part of the buildsystem and having access to more data like sources<br />
for a library target or even special target metadata, supporting other variants<br />
might be nice to have. Looking for proposals from experienced target<br />
metadata users here.</p>

<p>c) sharing metadata with kapidox<br />
Initially I placed these macros into the kapidox module, as this seems the<br />
logic place. And would match what kdoctools does for user manuals.<br />
Just, that would create a build dependency on kapidox which complicates usage<br />
a little. Having these macros in ECM delivers them with no extra effort<br />
needed.<br />
The data in metainfo.yaml is partially duplicated with the data feed into<br />
the macros. How to deduplicate that is still open. Especially with the need<br />
to not depend on external data sources like identify.kde.org.</p>

<p>d) naming pattern for cmake config variables for qch & tag files sane?</p>

<p>Issues:</p>

<ul class="remarkup-list">
<li class="remarkup-list-item">doxygen for me currently creates broken inter-qch links.</li>
<li class="remarkup-list-item">KDevelop for some created qch does not show the content (but assistant</li>
</ul>

<p>does).</p>

<ul class="remarkup-list">
<li class="remarkup-list-item">html style in assistant sometimes covers class names</li>
</ul></div></div><br /><div><strong>BRANCH</strong><div><div>addGenerateApiDox</div></div></div><br /><div><strong>REVISION DETAIL</strong><div><a href="https://phabricator.kde.org/D2854" rel="noreferrer">https://phabricator.kde.org/D2854</a></div></div><br /><div><strong>AFFECTED FILES</strong><div><div>modules/ECMDoxygenQCH.config.in<br />
modules/ECMGenerateApiDox.cmake</div></div></div><br /><div><strong>EMAIL PREFERENCES</strong><div><a href="https://phabricator.kde.org/settings/panel/emailpreferences/" rel="noreferrer">https://phabricator.kde.org/settings/panel/emailpreferences/</a></div></div><br /><div><strong>To: </strong>kossebau<br /><strong>Cc: </strong>ochurlaud, KDevelop, Frameworks<br /></div>