Commit bb2f9052 authored by Friedrich W. H. Kossebau's avatar Friedrich W. H. Kossebau
Browse files

API dox: move @cond/@endcond to doxygen comment style, to unconfuse doxygen

Doxygen currently does not generate documentation for e.g. Akonadi::Item,
as it seems to fail to properly parse the code (not sure exactly, might
be the template methods) and starts to misinterpret things.
Then all the conditional section markers are put into non-doxygen comments
so at least recent doxygen versions ignore them (given most markers have
been added around a decade ago perhaps earlier doxygen processed them).
But with doxygen getting confused while parsing, it seems to suddenly
handle some of the @cond and €endcond markers, but missing out the
matching start @cond or ending @endcond, and with that to fail even harder
to parse the rest.

Moving the markers into doxygen-processed comment style improves the
doxygen handling, and e.g. Akonadi::Item now gets documented.
parent 7870ade0
Pipeline #53001 passed with stage
in 12 minutes and 59 seconds
......@@ -306,7 +306,7 @@ void AgentBase::ObserverV4::itemsRelationsChanged(const Akonadi::Item::List &ite
}
}
//@cond PRIVATE
/// @cond PRIVATE
AgentBasePrivate::AgentBasePrivate(AgentBase *parent)
: q_ptr(parent)
......@@ -924,7 +924,7 @@ QString AgentBase::parseArguments(int argc, char **argv)
return identifier;
}
// @endcond
/// @endcond
int AgentBase::init(AgentBase &r)
{
......
......@@ -739,13 +739,13 @@ protected:
*/
void setTemporaryOffline(int makeOnlineInSeconds = 300);
//@cond PRIVATE
/// @cond PRIVATE
static void debugAgent(int argc, char **argv);
AgentBasePrivate *d_ptr;
explicit AgentBase(AgentBasePrivate *d, const QString &id);
friend class ObserverV2;
//@endcond
/// @endcond
/**
* This method is called whenever the @p online status has changed.
......@@ -757,7 +757,7 @@ protected:
virtual KAboutData aboutData() const;
private:
//@cond PRIVATE
/// @cond PRIVATE
static QString parseArguments(int argc, char **argv);
static int init(AgentBase &r);
void setOnlineInternal(bool state);
......@@ -781,7 +781,7 @@ private:
Q_PRIVATE_SLOT(d_func(), void slotResumedFromSuspend())
Q_PRIVATE_SLOT(d_func(), void slotTemporaryOfflineTimeout())
//@endcond
/// @endcond
};
}
......
......@@ -71,9 +71,9 @@ public:
void searchFinished(const QVector<QByteArray> &result);
private:
//@cond PRIVATE
/// @cond PRIVATE
AgentSearchInterfacePrivate *const d;
//@endcond
/// @endcond
};
}
......
......@@ -153,9 +153,9 @@ protected:
~PreprocessorBase() override;
private:
//@cond PRIVATE
/// @cond PRIVATE
Q_DECLARE_PRIVATE(PreprocessorBase)
//@endcond
/// @endcond
}; // class PreprocessorBase
......
......@@ -21,7 +21,7 @@ using namespace Akonadi;
qint64 ResourceScheduler::Task::latestSerial = 0;
static QDBusAbstractInterface *s_resourcetracker = nullptr;
//@cond PRIVATE
/// @cond PRIVATE
ResourceScheduler::ResourceScheduler(QObject *parent)
: QObject(parent)
......@@ -693,6 +693,6 @@ QDebug Akonadi::operator<<(QDebug d, const ResourceScheduler::Task &task)
return d;
}
//@endcond
/// @endcond
#include "moc_resourcescheduler_p.cpp"
......@@ -19,7 +19,7 @@ namespace Akonadi
{
class RecursiveMover;
//@cond PRIVATE
/// @cond PRIVATE
/**
@internal
......@@ -292,7 +292,7 @@ private:
QDebug operator<<(QDebug, const ResourceScheduler::Task &task);
QTextStream &operator<<(QTextStream &, const ResourceScheduler::Task &task);
//@endcond
/// @endcond
}
......
......@@ -80,9 +80,9 @@ public:
void itemSent(const Akonadi::Item &item, TransportResult result, const QString &message = QString());
private:
//@cond PRIVATE
/// @cond PRIVATE
TransportResourceBasePrivate *const d;
//@endcond
/// @endcond
};
}
......
......@@ -190,10 +190,10 @@ public:
void restart() const;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
QSharedDataPointer<Private> d;
//@endcond
/// @endcond
};
}
......
......@@ -348,7 +348,7 @@ AgentManager::AgentManager()
});
}
// @endcond
/// @endcond
AgentManager::~AgentManager() = default;
......
......@@ -186,11 +186,11 @@ Q_SIGNALS:
void instanceOnline(const Akonadi::AgentInstance &instance, bool online);
private:
//@cond PRIVATE
/// @cond PRIVATE
explicit AgentManager();
std::unique_ptr<AgentManagerPrivate> const d;
//@endcond
/// @endcond
};
}
......
......@@ -125,10 +125,10 @@ public:
bool operator==(const AgentType &other) const;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
QSharedDataPointer<Private> d;
//@endcond
/// @endcond
};
}
......
......@@ -38,9 +38,9 @@ namespace Akonadi
class AKONADICORE_EXPORT AttributeFactory
{
public:
//@cond PRIVATE
/// @cond PRIVATE
~AttributeFactory();
//@endcond
/// @endcond
/**
* Registers a custom attribute of type T.
......@@ -61,7 +61,7 @@ public:
static Attribute *createAttribute(const QByteArray &type);
protected:
//@cond PRIVATE
/// @cond PRIVATE
explicit AttributeFactory();
private:
......@@ -71,7 +71,7 @@ private:
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -62,10 +62,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -88,10 +88,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -62,10 +62,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -79,10 +79,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class EntityDeletedAttributePrivate;
const std::unique_ptr<EntityDeletedAttributePrivate> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -103,10 +103,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -81,10 +81,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -46,18 +46,18 @@ public:
*/
void setIndexingEnabled(bool enable);
//@cond PRIVATE
/// @cond PRIVATE
QByteArray type() const override;
Attribute *clone() const override;
QByteArray serialized() const override;
void deserialize(const QByteArray &data) override;
//@endcond
/// @endcond
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -149,18 +149,18 @@ public:
*/
bool isRecursive() const;
//@cond PRIVATE
/// @cond PRIVATE
QByteArray type() const override;
Attribute *clone() const override;
QByteArray serialized() const override;
void deserialize(const QByteArray &data) override;
//@endcond
/// @endcond
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -54,10 +54,10 @@ public:
void deserialize(const QByteArray &data) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -84,10 +84,10 @@ public:
private:
TagAttribute(const TagAttribute &other);
TagAttribute &operator=(const TagAttribute &other);
//@cond PRIVATE
/// @cond PRIVATE
class Private;
const std::unique_ptr<Private> d;
//@endcond
/// @endcond
};
} // namespace Akonadi
......
......@@ -142,10 +142,10 @@ public:
Q_REQUIRED_RESULT bool operator==(const CachePolicy &other) const;
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
QSharedDataPointer<Private> d;
//@endcond
/// @endcond
};
}
......
......@@ -96,14 +96,14 @@ Q_SIGNALS:
void nothingToReplay();
protected:
//@cond PRIVATE
/// @cond PRIVATE
explicit ChangeRecorder(ChangeRecorderPrivate *d, QObject *parent = nullptr);
//@endcond
/// @endcond
private:
//@cond PRIVATE
/// @cond PRIVATE
Q_DECLARE_PRIVATE(ChangeRecorder)
//@endcond
/// @endcond
};
}
......
......@@ -526,10 +526,10 @@ private:
void markAttributeModified(const QByteArray &type);
//@cond PRIVATE
/// @cond PRIVATE
QSharedDataPointer<CollectionPrivate> d_ptr;
friend class CollectionPrivate;
//@endcond
/// @endcond
};
AKONADICORE_EXPORT uint qHash(const Akonadi::Collection &collection);
......
......@@ -263,9 +263,9 @@ public:
Q_REQUIRED_RESULT bool isEmpty() const;
private:
//@cond PRIVATE
/// @cond PRIVATE
QSharedDataPointer<CollectionFetchScopePrivate> d;
//@endcond
/// @endcond
};
}
......
......@@ -17,7 +17,7 @@
using namespace Akonadi;
//@cond PRIVATE
/// @cond PRIVATE
class Akonadi::CollectionPathResolverPrivate : public JobPrivate
{
......@@ -215,6 +215,6 @@ void CollectionPathResolver::doStart()
});
}
//@endcond
/// @endcond
#include "moc_collectionpathresolver.cpp"
......@@ -130,10 +130,10 @@ public:
CollectionStatistics &operator=(const CollectionStatistics &other);
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
QSharedDataPointer<Private> d;
//@endcond
/// @endcond
};
}
......
......@@ -87,10 +87,10 @@ protected:
Control();
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
Private *const d;
//@endcond
/// @endcond
};
}
......
......@@ -563,7 +563,7 @@ public:
* Akonadi::super_trait for your class.
*/
template<typename T> void setPayload(const T &p);
//@cond PRIVATE
/// @cond PRIVATE
template<typename T> void setPayload(T *p);
// We know that auto_ptr is deprecated, but we still want to handle the case
......@@ -589,7 +589,7 @@ public:
#endif
#endif
template<typename T> void setPayload(std::unique_ptr<T> p);
//@endcond
/// @endcond
/**
* Returns the payload object of this PIM item. This method will only succeed if either
......@@ -674,7 +674,7 @@ public:
void setCachedPayloadParts(const QSet<QByteArray> &cachedParts);
private:
//@cond PRIVATE
/// @cond PRIVATE
friend class ItemCreateJob;
friend class ItemCreateJobPrivate;
friend class ItemModifyJob;
......@@ -738,7 +738,7 @@ private:
QSharedDataPointer<ItemPrivate> d_ptr;
friend class ItemPrivate;
//@endcond
/// @endcond
};
AKONADICORE_EXPORT uint qHash(const Akonadi::Item &item);
......
......@@ -412,9 +412,9 @@ public:
Q_REQUIRED_RESULT bool fetchRelations() const;
private:
//@cond PRIVATE
/// @cond PRIVATE
QSharedDataPointer<ItemFetchScopePrivate> d;
//@endcond
/// @endcond
};
}
......
......@@ -127,10 +127,10 @@ protected:
ItemFetchScope &fetchScope();
private:
//@cond PRIVATE
/// @cond PRIVATE
class Private;
Private *const d;
//@endcond
/// @endcond
Q_DISABLE_COPY(ItemMonitor)
};
......
......@@ -19,7 +19,7 @@
#include "exceptionbase.h"
//@cond PRIVATE Doxygen 1.7.1 hangs processing this file. so skip it.
/// @cond PRIVATE Doxygen 1.7.1 hangs processing this file. so skip it.
// for more info, see https://bugzilla.gnome.org/show_bug.cgi?id=531637
/* WARNING
......@@ -432,6 +432,6 @@ template<typename T> inline Payload<T> *payload_cast(PayloadBase *payloadBase)
} // namespace Akonadi
//@endcond
/// @endcond
#endif
......@@ -241,13 +241,13 @@ protected:
void slotResult(KJob *job) override;
private:
//@cond PRIVATE
/// @cond PRIVATE
Q_DECLARE_PRIVATE(ItemSync)
Q_PRIVATE_SLOT(d_func(), void slotLocalListDone(KJob *))
Q_PRIVATE_SLOT(d_func(), void slotTransactionResult(KJob *))
Q_PRIVATE_SLOT(d_func(), void slotItemsReceived(const Akonadi::Item::List &))
//@endcond
/// @endcond
};
}
......
......@@ -99,10 +99,10 @@ public:
void start() override;
private:
//@cond PRIVATE
/// @cond PRIVATE
friend class Akonadi::AgentInstanceCreateJobPrivate;
AgentInstanceCreateJobPrivate *const d;
//@endcond
/// @endcond
};
}
......
......@@ -61,10 +61,10 @@ public:
void start() override;
private:
//@cond PRIVATE
/// @cond PRIVATE
CollectionAttributesSynchronizationJobPrivate *const d;
friend class CollectionAttributesSynchronizationJobPrivate;
//@endcond
/// @endcond
};
}
......
......@@ -168,9 +168,9 @@ protected:
bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
protected Q_SLOTS: