1
0
mirror of https://github.com/qTox/qTox.git synced 2024-03-22 14:00:36 +08:00

docs(net): Added leading stars

This commit is contained in:
Diadlo 2016-08-01 11:21:49 +03:00
parent 902828fcc2
commit 956a04af8d
No known key found for this signature in database
GPG Key ID: 5AF9F2E29107C727
5 changed files with 199 additions and 199 deletions

View File

@ -40,11 +40,11 @@
#endif
/**
@file autoupdate.cpp
For now we only support auto updates on Windows and OS X, although extending it is not a technical issue.
Linux users are expected to use their package managers or update manually through official channels.
*/
* @file autoupdate.cpp
*
* For now we only support auto updates on Windows and OS X, although extending it is not a technical issue.
* Linux users are expected to use their package managers or update manually through official channels.
*/
#ifdef Q_OS_WIN
#ifdef Q_OS_WIN64
@ -80,47 +80,47 @@ unsigned char AutoUpdater::key[crypto_sign_PUBLICKEYBYTES];
#endif
/**
@var unsigned char AutoUpdater::UpdateFileMeta::sig[crypto_sign_BYTES]
@brief Signature of the file (ed25519)
@var QString AutoUpdater::UpdateFileMeta::id
@brief Unique id of the file
@var QString AutoUpdater::UpdateFileMeta::installpath
@brief Local path including the file name. May be relative to qtox-updater or absolute
@var uint64_t AutoUpdater::UpdateFileMeta::size
@brief Size in bytes of the file
*/
* @var unsigned char AutoUpdater::UpdateFileMeta::sig[crypto_sign_BYTES]
* @brief Signature of the file (ed25519)
*
* @var QString AutoUpdater::UpdateFileMeta::id
* @brief Unique id of the file
*
* @var QString AutoUpdater::UpdateFileMeta::installpath
* @brief Local path including the file name. May be relative to qtox-updater or absolute
*
* @var uint64_t AutoUpdater::UpdateFileMeta::size
* @brief Size in bytes of the file
*/
/**
@var static const QString AutoUpdater::updateServer
@brief Hostname of the qTox update server
@var static const QString AutoUpdater::platform
@brief Name of platform we're trying to get updates for
@var static const QString AutoUpdater::checkURI
@brief URI of the file containing the latest version string
@var static const QString AutoUpdater::flistURI
@brief URI of the file containing info on each file (hash, signature, size, name, ..)
@var static const QString AutoUpdater::filesURI
@brief URI of the actual files of the latest version
@var static const QString AutoUpdater::updaterBin
@brief Path to the qtox-updater binary
@var static std::atomic_bool AutoUpdater::abortFlag
@brief If true, try to abort everything.
@var static std::atomic_bool AutoUpdater::isDownloadingUpdate
@brief We'll pretend there's no new update available if we're already updating
@var static QMutex AutoUpdater::progressVersionMutex
@brief No, we can't just make the QString atomic
*/
* @var static const QString AutoUpdater::updateServer
* @brief Hostname of the qTox update server
*
* @var static const QString AutoUpdater::platform
* @brief Name of platform we're trying to get updates for
*
* @var static const QString AutoUpdater::checkURI
* @brief URI of the file containing the latest version string
*
* @var static const QString AutoUpdater::flistURI
* @brief URI of the file containing info on each file (hash, signature, size, name, ..)
*
* @var static const QString AutoUpdater::filesURI
* @brief URI of the actual files of the latest version
*
* @var static const QString AutoUpdater::updaterBin
* @brief Path to the qtox-updater binary
*
* @var static std::atomic_bool AutoUpdater::abortFlag
* @brief If true, try to abort everything.
*
* @var static std::atomic_bool AutoUpdater::isDownloadingUpdate
* @brief We'll pretend there's no new update available if we're already updating
*
* @var static QMutex AutoUpdater::progressVersionMutex
* @brief No, we can't just make the QString atomic
*/
const QString AutoUpdater::checkURI = AutoUpdater::updateServer+"/qtox/"+AutoUpdater::platform+"/version";
const QString AutoUpdater::flistURI = AutoUpdater::updateServer+"/qtox/"+AutoUpdater::platform+"/flist";
@ -132,18 +132,18 @@ QString AutoUpdater::progressVersion;
QMutex AutoUpdater::progressVersionMutex;
/**
@class AutoUpdater
@brief Handles checking and applying updates for qTox.
@note Do *NOT* use auto update unless AUTOUPDATE_ENABLED is defined to 1.
*/
* @class AutoUpdater
* @brief Handles checking and applying updates for qTox.
* @note Do *NOT* use auto update unless AUTOUPDATE_ENABLED is defined to 1.
*/
/**
@brief Checks if an update is available for download.
@return True if an update is available for download, false otherwise.
Connects to the qTox update server, and check if an update is available for download
Will call getUpdateVersion, and as such may block and processEvents.
*/
* @brief Checks if an update is available for download.
* @return True if an update is available for download, false otherwise.
*
* Connects to the qTox update server, and check if an update is available for download
* Will call getUpdateVersion, and as such may block and processEvents.
*/
bool AutoUpdater::isUpdateAvailable()
{
if (isDownloadingUpdate)
@ -159,10 +159,10 @@ bool AutoUpdater::isUpdateAvailable()
}
/**
@brief Fetch the version info of the last update available from the qTox update server
@note Will try to follow qTox's proxy settings, may block and processEvents
@return Avaliable version info.
*/
* @brief Fetch the version info of the last update available from the qTox update server
* @note Will try to follow qTox's proxy settings, may block and processEvents
* @return Avaliable version info.
*/
AutoUpdater::VersionInfo AutoUpdater::getUpdateVersion()
{
VersionInfo versionInfo;
@ -228,10 +228,10 @@ AutoUpdater::VersionInfo AutoUpdater::getUpdateVersion()
}
/**
@brief Parses and validates a flist file.
@param flistData Install file data.
@return An empty list on error.
*/
* @brief Parses and validates a flist file.
* @param flistData Install file data.
* @return An empty list on error.
*/
QList<AutoUpdater::UpdateFileMeta> AutoUpdater::parseFlist(QByteArray flistData)
{
QList<UpdateFileMeta> flist;
@ -292,10 +292,10 @@ QList<AutoUpdater::UpdateFileMeta> AutoUpdater::parseFlist(QByteArray flistData)
}
/**
@brief Gets the update server's flist.
@note Will try to follow qTox's proxy settings, may block and processEvents
@return An empty array on error
*/
* @brief Gets the update server's flist.
* @note Will try to follow qTox's proxy settings, may block and processEvents
* @return An empty array on error
*/
QByteArray AutoUpdater::getUpdateFlist()
{
QByteArray flist;
@ -326,10 +326,10 @@ QByteArray AutoUpdater::getUpdateFlist()
}
/**
@brief Generates a list of files we need to update.
@param updateFlist List of files available to update.
@return List of files we need to update.
*/
* @brief Generates a list of files we need to update.
* @param updateFlist List of files available to update.
* @return List of files we need to update.
*/
QList<AutoUpdater::UpdateFileMeta> AutoUpdater::genUpdateDiff(QList<UpdateFileMeta> updateFlist)
{
QList<UpdateFileMeta> diff;
@ -342,10 +342,10 @@ QList<AutoUpdater::UpdateFileMeta> AutoUpdater::genUpdateDiff(QList<UpdateFileMe
}
/**
@brief Checks if we have an up to date version of this file locally installed.
@param fileMeta File to check.
@return True if file doesn't need updates, false if need.
*/
* @brief Checks if we have an up to date version of this file locally installed.
* @param fileMeta File to check.
* @return True if file doesn't need updates, false if need.
*/
bool AutoUpdater::isUpToDate(AutoUpdater::UpdateFileMeta fileMeta)
{
QString appDir = qApp->applicationDirPath();
@ -362,13 +362,13 @@ bool AutoUpdater::isUpToDate(AutoUpdater::UpdateFileMeta fileMeta)
}
/**
@brief Tries to fetch the file from the update server.
@note Note that a file with an empty but non-null QByteArray is not an error, merely a file of size 0.
@note Will try to follow qTox's proxy settings, may block and processEvents.
@param fileMeta Meta data fo file to update.
@param progressCallback Callback function, which will connected with QNetworkReply::downloadProgress
@return A file with a null QByteArray on error.
*/
* @brief Tries to fetch the file from the update server.
* @note Note that a file with an empty but non-null QByteArray is not an error, merely a file of size 0.
* @note Will try to follow qTox's proxy settings, may block and processEvents.
* @param fileMeta Meta data fo file to update.
* @param progressCallback Callback function, which will connected with QNetworkReply::downloadProgress
* @return A file with a null QByteArray on error.
*/
AutoUpdater::UpdateFile AutoUpdater::getUpdateFile(UpdateFileMeta fileMeta,
std::function<void(int,int)> progressCallback)
{
@ -402,10 +402,10 @@ AutoUpdater::UpdateFile AutoUpdater::getUpdateFile(UpdateFileMeta fileMeta,
}
/**
@brief Will try to download an update, if successful qTox will apply it after a restart
@note Will try to follow qTox's proxy settings, may block and processEvents
@result True if successful and qTox will apply it after a restart
*/
* @brief Will try to download an update, if successful qTox will apply it after a restart
* @note Will try to follow qTox's proxy settings, may block and processEvents
* @result True if successful and qTox will apply it after a restart
*/
bool AutoUpdater::downloadUpdate()
{
// Updates only for supported platforms
@ -534,12 +534,12 @@ fail:
}
/**
@brief Checks if an update is downloaded and ready to be installed.
@note If result is true, call installLocalUpdate,
@return True if an update is downloaded, false if partially downloaded.
If an update was partially downloaded, the function will resume asynchronously and return false.
*/
* @brief Checks if an update is downloaded and ready to be installed.
* @note If result is true, call installLocalUpdate,
* @return True if an update is downloaded, false if partially downloaded.
*
* If an update was partially downloaded, the function will resume asynchronously and return false.
*/
bool AutoUpdater::isLocalUpdateReady()
{
// Updates only for supported platforms
@ -580,12 +580,12 @@ bool AutoUpdater::isLocalUpdateReady()
}
/**
@brief Launches the qTox updater to try to install the local update and exits immediately.
@note Will not check that the update actually exists, use isLocalUpdateReady first for that.
The qTox updater will restart us after the update is done.
If we fail to start the qTox updater, we will delete the update and exit.
*/
* @brief Launches the qTox updater to try to install the local update and exits immediately.
*
* @note Will not check that the update actually exists, use isLocalUpdateReady first for that.
* The qTox updater will restart us after the update is done.
* If we fail to start the qTox updater, we will delete the update and exit.
*/
void AutoUpdater::installLocalUpdate()
{
qDebug() << "About to start the qTox updater to install a local update";
@ -626,13 +626,13 @@ void AutoUpdater::installLocalUpdate()
}
/**
@brief Checks update an show dialog asking to download it.
@note Runs asynchronously in its own thread, and will return immediatly
Will call isUpdateAvailable, and as such may processEvents.
Connects to the qTox update server, if an update is found
shows a dialog to the user asking to download it.
*/
* @brief Checks update an show dialog asking to download it.
* @note Runs asynchronously in its own thread, and will return immediatly
*
* Will call isUpdateAvailable, and as such may processEvents.
* Connects to the qTox update server, if an update is found
* shows a dialog to the user asking to download it.
*/
void AutoUpdater::checkUpdatesAsyncInteractive()
{
if (isDownloadingUpdate)
@ -642,10 +642,10 @@ void AutoUpdater::checkUpdatesAsyncInteractive()
}
/**
@brief Does the actual work for checkUpdatesAsyncInteractive
Blocking, but otherwise has the same properties than checkUpdatesAsyncInteractive
*/
* @brief Does the actual work for checkUpdatesAsyncInteractive
*
* Blocking, but otherwise has the same properties than checkUpdatesAsyncInteractive
*/
void AutoUpdater::checkUpdatesAsyncInteractiveWorker()
{
if (!isUpdateAvailable())
@ -685,9 +685,9 @@ void AutoUpdater::checkUpdatesAsyncInteractiveWorker()
}
/**
@brief Thread safe setter
@param version Version to set.
*/
* @brief Thread safe setter
* @param version Version to set.
*/
void AutoUpdater::setProgressVersion(QString version)
{
QMutexLocker lock(&progressVersionMutex);
@ -695,11 +695,11 @@ void AutoUpdater::setProgressVersion(QString version)
}
/**
@brief Abort update process.
@note Aborting will make some functions try to return early.
Call before qTox exits to avoid the updater running in the background.
*/
* @brief Abort update process.
*
* @note Aborting will make some functions try to return early.
* Call before qTox exits to avoid the updater running in the background.
*/
void AutoUpdater::abortUpdates()
{
abortFlag = true;
@ -707,8 +707,8 @@ void AutoUpdater::abortUpdates()
}
/**
@brief Functions giving info on the progress of update downloads.
@return Version as string.
* @brief Functions giving info on the progress of update downloads.
* @return Version as string.
*/
QString AutoUpdater::getProgressVersion()
{

View File

@ -24,12 +24,12 @@
#include <QDebug>
/**
@class AvatarBroadcaster
Takes care of broadcasting avatar changes to our friends in a smart way
Cache a copy of our current avatar and friends who have received it
so we don't spam avatar transfers to a friend who already has it.
*/
* @class AvatarBroadcaster
*
* Takes care of broadcasting avatar changes to our friends in a smart way
* Cache a copy of our current avatar and friends who have received it
* so we don't spam avatar transfers to a friend who already has it.
*/
QByteArray AvatarBroadcaster::avatarData;
QMap<uint32_t, bool> AvatarBroadcaster::friendsSentTo;
@ -41,9 +41,9 @@ static auto autoBroadcast = [](uint32_t friendId, Status)
};
/**
@brief Set our current avatar.
@param data Byte array on avater.
*/
* @brief Set our current avatar.
* @param data Byte array on avater.
*/
void AvatarBroadcaster::setAvatar(QByteArray data)
{
if (avatarData == data)
@ -58,9 +58,9 @@ void AvatarBroadcaster::setAvatar(QByteArray data)
}
/**
@brief Send our current avatar to this friend, if not already sent
@param friendId Id of friend to send avatar.
*/
* @brief Send our current avatar to this friend, if not already sent
* @param friendId Id of friend to send avatar.
*/
void AvatarBroadcaster::sendAvatarTo(uint32_t friendId)
{
if (friendsSentTo.contains(friendId) && friendsSentTo[friendId])
@ -72,9 +72,9 @@ void AvatarBroadcaster::sendAvatarTo(uint32_t friendId)
}
/**
@brief Setup auto broadcast sending avatar.
@param state If true, we automatically broadcast our avatar to friends when they come online.
*/
* @brief Setup auto broadcast sending avatar.
* @param state If true, we automatically broadcast our avatar to friends when they come online.
*/
void AvatarBroadcaster::enableAutoBroadcast(bool state)
{
QObject::disconnect(autoBroadcastConn);

View File

@ -30,20 +30,20 @@
#define TOX_HEX_ID_LENGTH 2*TOX_ADDRESS_SIZE
/**
@class ToxDNS
@brief Handles tox1 and tox3 DNS queries.
*/
* @class ToxDNS
* @brief Handles tox1 and tox3 DNS queries.
*/
/**
@struct tox3_server
@brief Represents a tox3 server.
@var const char* tox3_server::name
@brief Hostname of the server, e.g. toxme.se.
@var uint8_t* tox3_server::pubkey
@brief Public key of the tox3 server, usually 256bit long.
*/
* @struct tox3_server
* @brief Represents a tox3 server.
*
* @var const char* tox3_server::name
* @brief Hostname of the server, e.g. toxme.se.
*
* @var uint8_t* tox3_server::pubkey
* @brief Public key of the tox3 server, usually 256bit long.
*/
const ToxDNS::tox3_server ToxDNS::pinnedServers[]
{
@ -67,11 +67,11 @@ void ToxDNS::showWarning(const QString &message)
}
/**
@brief Try to fetch the first entry of the given TXT record.
@param record Record to search.
@param silent May display message boxes on error if silent is false.
@return An empty object on failure. May block for up to ~3s.
*/
* @brief Try to fetch the first entry of the given TXT record.
* @param record Record to search.
* @param silent May display message boxes on error if silent is false.
* @return An empty object on failure. May block for up to ~3s.
*/
QByteArray ToxDNS::fetchLastTextRecord(const QString& record, bool silent)
{
QDnsLookup dns;
@ -131,13 +131,13 @@ QByteArray ToxDNS::fetchLastTextRecord(const QString& record, bool silent)
}
/**
@brief Send query to DNS to find Tox Id.
@note Will *NOT* fallback on queryTox1 anymore.
@param server Server to sending query.
@param record Should look like user@domain.tld.
@param silent If true, there will be no output on error.
@return Tox Id string.
*/
* @brief Send query to DNS to find Tox Id.
* @note Will *NOT* fallback on queryTox1 anymore.
* @param server Server to sending query.
* @param record Should look like user@domain.tld.
* @param silent If true, there will be no output on error.
* @return Tox Id string.
*/
QString ToxDNS::queryTox3(const tox3_server& server, const QString &record, bool silent)
{
QByteArray nameData = record.left(record.indexOf('@')).toUtf8(), id, realRecord;
@ -218,11 +218,11 @@ fallbackOnTox1:
}
/**
@brief Tries to map a text string to a ToxId struct, will query Tox DNS records if necessary.
@param address Adress to search for Tox ID.
@param silent If true, there will be no output on error.
@return Found Tox Id.
*/
* @brief Tries to map a text string to a ToxId struct, will query Tox DNS records if necessary.
* @param address Adress to search for Tox ID.
* @param silent If true, there will be no output on error.
* @return Found Tox Id.
*/
ToxId ToxDNS::resolveToxAddress(const QString &address, bool silent)
{
if (address.isEmpty())

View File

@ -31,12 +31,12 @@
#include <ctime>
/**
@class Toxme
@brief This class implements a client for the toxme.se API
@note The class is thread safe
@note May process events while waiting for blocking calls
*/
* @class Toxme
* @brief This class implements a client for the toxme.se API
*
* @note The class is thread safe
* @note May process events while waiting for blocking calls
*/
QByteArray Toxme::makeJsonRequest(QString url, QString json, QNetworkReply::NetworkError &error)
{
@ -145,10 +145,10 @@ QByteArray Toxme::prepareEncryptedJson(QString url, int action, QString payload)
}
/**
@brief Converts a toxme address to a Tox ID.
@param address Toxme address.
@return Found ToxId (an empty ID on error).
*/
* @brief Converts a toxme address to a Tox ID.
* @param address Toxme address.
* @return Found ToxId (an empty ID on error).
*/
ToxId Toxme::lookup(QString address)
{
// JSON injection ?
@ -218,15 +218,15 @@ Toxme::ExecCode Toxme::extractError(QString json)
}
/**
@brief Creates a new toxme address associated with a Tox ID.
@param[out] code Tox error code @see getErrorMessage.
@param[in] server Create toxme account on this server.
@param[in] id ToxId of current user.
@param[in] address Create toxme account with this adress.
@param[in] keepPrivate If true, the address will not be published on toxme site.
@param[in] bio A short optional description of yourself if you want to publish your address.
@return password on success, else sets code parameter and returns an empty QString.
*/
* @brief Creates a new toxme address associated with a Tox ID.
* @param[out] code Tox error code @see getErrorMessage.
* @param[in] server Create toxme account on this server.
* @param[in] id ToxId of current user.
* @param[in] address Create toxme account with this adress.
* @param[in] keepPrivate If true, the address will not be published on toxme site.
* @param[in] bio A short optional description of yourself if you want to publish your address.
* @return password on success, else sets code parameter and returns an empty QString.
*/
QString Toxme::createAddress(ExecCode &code, QString server, ToxId id, QString address,
bool keepPrivate, QString bio)
{
@ -295,11 +295,11 @@ QString Toxme::getPass(QString json, ExecCode &code) {
}
/**
@brief Deletes the address associated with your current Tox ID.
@param server Server to delete the address from.
@param id ToxId to delete.
@return Status code returned from server.
*/
* @brief Deletes the address associated with your current Tox ID.
* @param server Server to delete the address from.
* @param id ToxId to delete.
* @return Status code returned from server.
*/
Toxme::ExecCode Toxme::deleteAddress(QString server, ToxId id)
{
const QString payload{"{\"public_key\":\""+id.toString().left(64)+"\","
@ -318,10 +318,10 @@ Toxme::ExecCode Toxme::deleteAddress(QString server, ToxId id)
}
/**
@brief Return string of the corresponding error code
@param errorCode Code to get error message
@return Source error message
*/
* @brief Return string of the corresponding error code
* @param errorCode Code to get error message
* @return Source error message
*/
QString Toxme::getErrorMessage(int errorCode)
{
switch (errorCode) {
@ -365,10 +365,10 @@ QString Toxme::getErrorMessage(int errorCode)
}
/**
@brief Return translated error message
@param errorCode Code to translate
@return Translated Toxme error message
*/
* @brief Return translated error message
* @param errorCode Code to translate
* @return Translated Toxme error message
*/
QString Toxme::translateErrorMessage(int errorCode)
{
switch (errorCode) {

View File

@ -45,11 +45,11 @@ bool toxURIEventHandler(const QByteArray& eventData)
}
/**
@brief Shows a dialog asking whether or not to add this tox address as a friend.
@note Will wait until the core is ready first.
@param toxURI Tox URI to try to add.
@return True, if tox URI is correct, false otherwise.
*/
* @brief Shows a dialog asking whether or not to add this tox address as a friend.
* @note Will wait until the core is ready first.
* @param toxURI Tox URI to try to add.
* @return True, if tox URI is correct, false otherwise.
*/
bool handleToxURI(const QString &toxURI)
{
Core* core = Core::getInstance();