chore: Small API doc fixes #2735
3 checks passed!
Status: PASS
Details
✔️ Validator: TITLE
- ✔️ All the requisite validations passed for 'or' option
Input : chore: Small API doc fixes
Settings :{"or":[{"must_include":{"regex":"^(feat|docs|chore|cleanup|fix|refactor|test|style|perf)(\\(\\w+\\))?:\\ .+$","message":"Semantic release conventions must be followed."}},{"must_include":{"regex":"^Bump [^ ]* from [^ ]* to [^ ]*$","message":"Dependabot PRs are exempt from semantic release conventions."}}]}
✔️ Validator: COMMIT
- ✔️ Your commit messages met the specified criteria
Input : docs: Update user data API explanation
There is no APIDSL so it shouldn't be mentioned, nor are there old style
callbacks that take user data when registering them.,docs: Public headers, tox -> Tox,docs: Public headers, null -> NULL,docs: Public headers, 80 column width comments,docs: Public headers, spellcheck,docs: Public headers, NULL-terminated -> NUL-terminated
Matching the way tox.h words it.,docs: Public headers, events_alloc -> internal,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.
Settings : {"do":"commit","message":{"regex":"^((feat|docs|chore|cleanup|fix|refactor|test|style|perf)(\\(\\w+\\))?:\\ .+|Bump [^ ]* from [^ ]* to [^ ]*)","message":"Semantic release conventions must be followed."}}
✔️ Validator: DESCRIPTION
- ✔️ description must exclude '\[ \]'
Input : API docs are a bit inconsistent:
- sometimes use "tox" instead of "Tox"
- sometimes use "null" instead of "NULL"
- sometimes calls strings NUL-terminated, other times NULL terminated
- sometimes comments go over 80 columns
- sometimes
@param
are listed after@return
- sometimes it's a function, other times it's a `function`, and yet other times it's a `function()`, same for parameters or `parameters` -- oh, and sometimes a single comment mixes multiple styles! (e.g. tox_group_get_topic)
- NGC functions doesn't use
@breif
for some reason when all other functions do. Why? - some functions don't document their parameters, e.g. tox_group_set_topic, while others document even the obvious most parameters.
This PR addresses only the first 4 points, and one case of the 5th point that I have noticed by an accident.
5-8 points are not addressed. Would be nice if someone could address those.
Settings : {"must_exclude":{"regex":"\\\\[ \\\\]","message":"There are incomplete TODO task(s) unchecked."}}