Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Small API doc fixes #2735

Merged
merged 8 commits into from
Mar 14, 2024

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

a3d1b85
Select commit
Loading
Failed to load commit list.
Merged

chore: Small API doc fixes #2735

docs: Public headers, Core/toxcore -> Tox/the Tox library
a3d1b85
Select commit
Loading
Failed to load commit list.
Mergeable / Mergeable succeeded Mar 13, 2024 in 1s

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:
  1. sometimes use "tox" instead of "Tox"
  2. sometimes use "null" instead of "NULL"
  3. sometimes calls strings NUL-terminated, other times NULL terminated
  4. sometimes comments go over 80 columns
  5. sometimes @param are listed after @return
  6. 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)
  7. NGC functions doesn't use @breif for some reason when all other functions do. Why?
  8. 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.


This change is Reviewable

Settings : {"must_exclude":{"regex":"\\\\[ \\\\]","message":"There are incomplete TODO task(s) unchecked."}}