StarMirror
/
toxcore
mirror of https://github.com/irungentoo/toxcore
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Public headers, Core/toxcore -> Tox/the Tox library 

Toxcore public header documentation suffers from an identity crisis. It calls
itself three different things: Tox, toxcore and Core, depending on the
time period the comment was written in, the author of the comment,
whether the comment refers to the Tox instance or the Tox[core] library
(it doesn't seem like anything refers to the Tox protocol?), and maybe
some other nuances.

No one really calls it Core though, so this commit replaces the use of
Core with Tox/toxcore, and edits other instances of the documentation
referring to the library where I thought rewording was in order, though
in the end it's more of a subjective personal preference.
pull/1660/head
Maxim Biro 2024-03-10 19:57:36 -04:00
parent f78d0f3f39
commit a3d1b8595c
No known key found for this signature in database
GPG Key ID: AB3AD9896472BFA4
2 changed files with 29 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
toxav/toxav.h
View File

@ -12,14 +12,14 @@
*
* @section av_events Events and callbacks
*
* As in Core API, events are handled by callbacks. One callback can be
* As in the toxcore API, events are handled by callbacks. One callback can be
* registered per event. All events have a callback function type named
* `toxav_{event}_cb` and a function to register it named
* `toxav_callback_{event}`. Passing a NULL callback will result in no callback
* being registered for that event. Only one callback per event can be
* registered, so if a client needs multiple event listeners, it needs to
* implement the dispatch functionality itself. Unlike Core API, lack of some
* event handlers will cause the the library to drop calls before they are
* implement the dispatch functionality itself. Unlike the toxcore API, lack of
* some event handlers will cause the the library to drop calls before they are
* started. Hanging up call from a callback causes undefined behaviour.
*
* @section av_threading Threading implications
@ -609,8 +609,8 @@ bool toxav_audio_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra
/**
* The function type for the audio_bit_rate callback. The event is triggered
* when the network becomes too saturated for current bit rates at which
* point core suggests new bit rates.
* when the network becomes too saturated for current bit rates at which point
* ToxAV suggests new bit rates.
*
* @param friend_number The friend number of the friend for which to set the
* bit rate.
@ -659,8 +659,8 @@ bool toxav_video_set_bit_rate(ToxAV *av, uint32_t friend_number, uint32_t bit_ra
/**
* The function type for the video_bit_rate callback. The event is triggered
* when the network becomes too saturated for current bit rates at which
* point core suggests new bit rates.
* when the network becomes too saturated for current bit rates at which point
* ToxAV suggests new bit rates.
*
* @param friend_number The friend number of the friend for which to set the
* bit rate.

45
toxcore/tox.h
View File

@ -197,7 +197,7 @@ bool tox_version_is_compatible(uint32_t major, uint32_t minor, uint32_t patch);
*
* The values of these are not part of the ABI. Prefer to use the function
* versions of them for code that should remain compatible with future versions
* of toxcore.
* of the Tox library.
*/
/**
@ -473,8 +473,7 @@ typedef enum Tox_Log_Level {
const char *tox_log_level_to_string(Tox_Log_Level value);
/**
* @brief This event is triggered when the toxcore library logs an internal
* message.
* @brief This event is triggered when Tox logs an internal message.
*
* This is mostly useful for debugging. This callback can be called from any
* function, not just tox_iterate. This means the user data lifetime must at
@ -541,8 +540,8 @@ struct Tox_Options {
* need to be relayed through a TCP relay node, potentially slowing them
* down.
*
* If a proxy is enabled, UDP will be disabled if either toxcore or the
* proxy don't support proxying UDP messages.
* If a proxy is enabled, UDP will be disabled if either the Tox library or
* the proxy don't support proxying UDP messages.
*/
bool udp_enabled;
@ -621,7 +620,7 @@ struct Tox_Options {
uint16_t tcp_port;
/**
* Enables or disables UDP hole-punching in toxcore. (Default: enabled).
* Enables or disables UDP hole-punching. (Default: enabled).
*/
bool hole_punching_enabled;
@ -633,8 +632,8 @@ struct Tox_Options {
/**
* The savedata.
*
* The data pointed at by this member is owned by the user, so must
* outlive the options object.
* The data pointed at by this member is owned by the user, so must outlive
* the options object.
*/
const uint8_t *savedata_data;
@ -1934,9 +1933,9 @@ bool tox_hash(uint8_t hash[TOX_HASH_LENGTH], const uint8_t data[], size_t length
/**
* @brief A list of pre-defined file kinds.
*
* Toxcore itself does not behave differently for different file kinds. These
* are a hint to the client telling it what use the sender intended for the
* file. The `kind` parameter in the send function and recv callback are
* The Tox library itself does not behave differently for different file kinds.
* These are a hint to the client telling it what use the sender intended for
* the file. The `kind` parameter in the send function and recv callback are
* `uint32_t`, not Tox_File_Kind, because clients can invent their own file
* kind. Unknown file kinds should be treated as TOX_FILE_KIND_DATA.
*/
@ -2240,8 +2239,8 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value);
* File transmission occurs in chunks, which are requested through the
* `file_chunk_request` event.
*
* When a friend goes offline, all file transfers associated with the friend are
* purged from core.
* When a friend goes offline, all file transfers associated with the friend get
* purged.
*
* If the file contents change during a transfer, the behaviour is unspecified
* in general. What will actually happen depends on the mode in which the file
@ -2251,7 +2250,7 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value);
* - and sending mode was streaming (file_size = UINT64_MAX), the behaviour
* will be as expected.
* - and sending mode was file (file_size != UINT64_MAX), the
* file_chunk_request callback will receive length = 0 when Core thinks the
* file_chunk_request callback will receive length = 0 when Tox thinks the
* file transfer has finished. If the client remembers the file size as it
* was when sending the request, it will terminate the transfer normally. If
* the client re-reads the size, it will think the friend cancelled the
@ -2275,9 +2274,9 @@ const char *tox_err_file_send_to_string(Tox_Err_File_Send value);
* @param file_size Size in bytes of the file the client wants to send,
* UINT64_MAX if unknown or streaming.
* @param file_id A file identifier of length TOX_FILE_ID_LENGTH that can be
* used to uniquely identify file transfers across core restarts. If NULL, a
* random one will be generated by core. It can then be obtained by using
* `tox_file_get_file_id()`.
* used to uniquely identify file transfers across Tox restarts. If NULL, a
* random one will be generated by the library. It can then be obtained by
* using `tox_file_get_file_id()`.
* @param filename Name of the file. Does not need to be the actual name. This
* name will be sent along with the file send request.
* @param filename_length Size in bytes of the filename.
@ -2355,9 +2354,9 @@ const char *tox_err_file_send_chunk_to_string(Tox_Err_File_Send_Chunk value);
* This function is called in response to the `file_chunk_request` callback. The
* length parameter should be equal to the one received though the callback.
* If it is zero, the transfer is assumed complete. For files with known size,
* Core will know that the transfer is complete after the last byte has been
* Tox will know that the transfer is complete after the last byte has been
* received, so it is not necessary (though not harmful) to send a zero-length
* chunk to terminate. For streams, core will know that the transfer is finished
* chunk to terminate. For streams, Tox will know that the transfer is finished
* if a chunk with length less than the length requested in the callback is
* sent.
*
@ -2401,7 +2400,7 @@ typedef void tox_file_chunk_request_cb(
*
* Pass NULL to unset.
*
* This event is triggered when Core is ready to send more file data.
* This event is triggered when Tox is ready to send more file data.
*/
void tox_callback_file_chunk_request(Tox *tox, tox_file_chunk_request_cb *callback);
@ -2921,7 +2920,7 @@ const char *tox_err_conference_join_to_string(Tox_Err_Conference_Join value);
* to it until a handshaking procedure has been completed. A
* `conference_connected` event will then occur for the conference. The client
* will then remain connected to the conference until the conference is deleted,
* even across core restarts. Many operations on a conference will fail with a
* even across Tox restarts. Many operations on a conference will fail with a
* corresponding error if attempted on a conference to which the client is not
* yet connected.
*
@ -3075,8 +3074,8 @@ size_t tox_conference_get_chatlist_size(const Tox *tox);
* Determine how much space to allocate for the array with the
* `tox_conference_get_chatlist_size` function.
*
* Note that `tox_get_savedata` saves all connected conferences;
* when toxcore is created from savedata in which conferences were saved, those
* Note that `tox_get_savedata` saves all connected conferences; when a Tox
* instance is created from savedata in which conferences were saved, those
* conferences will be connected at startup, and will be listed by
* `tox_conference_get_chatlist`.
*