Details
-
Bug
-
Resolution: Done
-
P2: Important
-
5.0.1
-
None
-
5c994caf2243b463c6a81bc892beac45a5b7e8be
Description
Example:
import QtQuick 2.0 /*! \qmltype FancyControl \inqmlmodule QtQuick.Controls 1.0 \brief A fancy QML control for qdoc demonstration purposes. Foo bar.... */ Item { /*! A fancy documented signal. */ signal fancySignal /*! A fancy documented property. */ property var fancyProperty // an internal implementation detail that the user cannot // even access, and should therefore NOT appear in the docs onFancySignal: { } // an internal implementation detail that the user cannot // even access, and should therefore NOT appear in the docs onFancyPropertyChanged: { } }
The above signal handler implementations should not appear in the docs. We have already documented 'fancySignal' and 'fancyProperty', as those are actually visible to the user of the control. It is an internal implementation detail if this control listens to the signal or property changes by implementing its own signal handlers. Those internal signal handler implementations are not visible nor accessible to the user of the control. Therefore they should not be automatically picked up by qdoc.
The workaround is to mark all top level signal handlers with /*! \internal */ but we would like to avoid bloating our codebase with that. Developers also keep forgetting to add the \internal tag (because they don't even expect it to appear in the docs).