docs: clean up headerdocs

[armcknight]

After making some of the changes in #2804 , I noticed some other irregularities in nearby headerdocs.

• set aside all declarations of default values in separate @note entries
• add @c to sentry and builtin declared symbols in headerdocs and other tokens that are better viewed in monospace,
  • like values that can be supplied to a documented method: 0 is easy to mistake as O in variable-width fonts, but 0 and O are better because of the slash through the monospace 0.
  • Also, tokens containing underscores would cause all subsequent text to be rendered as italic due to the markdown rendering, which doesn't happen if it is preceded by a @c
• some light editing of typos, whitespace and extra newlines; reworded some phrasing to be more clear
• removed some, but probably not all, superfluous headerdocs. things like a doc over an init method for class Foo that states @returns Foo (example). I'd rather just save that line and vertical space.
• standardize on @c for monospaced elements in headerdocs. This gives it treatment in the source file and in doc popovers.
  • while backticks do make it monospaced in source files, it doesn't in doc popovers
    • before:
      
    • after:
      
  • <code></code doesn't appear to do anything:
    • before:
      
      
    • after:
      
      

#skip-changelog

[armcknight]

Hmm, I just noticed the Build Documentation feature in Xcode, which @c doesn't play well with. And while I see some cross-reference links created for tokens surrounded by double-backticks, that doesn't work perfectly. Since we didn't really use that feature, I think we should stick with @c for now.

[github-actions]

Performance metrics 🚀

	Plain	With Sentry	Diff
Startup time	1193.50 ms	1229.90 ms	36.40 ms
Size	20.76 KiB	425.81 KiB	405.04 KiB

Baseline results on branch: main

Startup times

Revision	Plain	With Sentry	Diff
8f397a7	1196.55 ms	1226.82 ms	30.27 ms
8f397a7	1252.37 ms	1274.80 ms	22.43 ms
7bc3c0d	1212.35 ms	1228.94 ms	16.59 ms
ce4cfaf	1203.61 ms	1218.86 ms	15.25 ms
06548c0	1226.71 ms	1252.37 ms	25.66 ms
4259afd	1222.12 ms	1249.74 ms	27.62 ms
7fb7afb	1235.00 ms	1256.81 ms	21.81 ms
369222e	1232.14 ms	1258.90 ms	26.76 ms
c9724f9	1199.38 ms	1229.54 ms	30.16 ms
28333b6	1247.29 ms	1262.51 ms	15.22 ms

App size

Revision	Plain	With Sentry	Diff
8f397a7	20.76 KiB	420.55 KiB	399.79 KiB
8f397a7	20.76 KiB	420.55 KiB	399.79 KiB
7bc3c0d	20.76 KiB	427.35 KiB	406.59 KiB
ce4cfaf	20.76 KiB	423.19 KiB	402.43 KiB
06548c0	20.76 KiB	427.36 KiB	406.59 KiB
4259afd	20.76 KiB	419.70 KiB	398.94 KiB
7fb7afb	20.76 KiB	419.69 KiB	398.94 KiB
369222e	20.76 KiB	419.67 KiB	398.91 KiB
c9724f9	20.76 KiB	427.66 KiB	406.90 KiB
28333b6	20.76 KiB	424.69 KiB	403.93 KiB

Previous results on branch: armcknight/docs/standardize-format-defaults-and-monospaced-elements

Startup times

Revision	Plain	With Sentry	Diff
bda1d49	1249.94 ms	1268.84 ms	18.90 ms

App size

Revision	Plain	With Sentry	Diff
bda1d49	20.76 KiB	425.81 KiB	405.04 KiB

[codecov]

Codecov Report

Merging #2829 (e84f91a) into main (9d56232) will increase coverage by 0.03%.
The diff coverage is n/a.

❗ Current head e84f91a differs from pull request most recent head 83cd1f5. Consider uploading reports for the commit 83cd1f5 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2829      +/-   ##
==========================================
+ Coverage   81.30%   81.33%   +0.03%     
==========================================
  Files         258      258              
  Lines       24131    24150      +19     
  Branches    10706    10719      +13     
==========================================
+ Hits        19619    19642      +23     
+ Misses       4014     4011       -3     
+ Partials      498      497       -1     

Impacted Files	Coverage Δ
Sources/Sentry/SentryAppStateManager.m	100.00% <ø> (ø)
Sources/Sentry/SentryCrashReportConverter.m	93.93% <ø> (ø)
Sources/Sentry/SentryDevice.mm	53.09% <ø> (ø)
Sources/Sentry/SentryHttpTransport.m	97.73% <ø> (ø)
Sources/Sentry/SentryHub.m	95.98% <ø> (ø)
Sources/Sentry/SentryMetricKitIntegration.m	99.60% <ø> (ø)
Sources/Sentry/SentryNSURLSessionTaskSearch.m	100.00% <ø> (ø)
Sources/Sentry/SentryOptions.m	96.99% <ø> (ø)
Sources/Sentry/SentryReachability.m	81.81% <ø> (ø)
Sources/Sentry/SentrySDK.m	86.20% <ø> (ø)
... and 9 more

... and 4 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9d56232...83cd1f5. Read the comment docs.

[philipphofmann]

Hmm, I just noticed the Build Documentation feature in Xcode, which @c doesn't play well with. And while I see some cross-reference links created for tokens surrounded by double-backticks, that doesn't work perfectly. Since we didn't really use that feature, I think we should stick with @c for now.

We can revisit this once we start publishing code docs.

[philipphofmann]

Many thanks for doing this 👏 💯 🥇

Please merge this quickly to avoid conflicts. LGTM 🌟

[armcknight]

@philipphofmann This was the first time I encountered the high risk file check, note that I added the new sha to its output to tighten up the round trip in that workflow a bit: https://github.com/getsentry/sentry-cocoa/pull/2829/files#diff-9219d0ee596a5725e4e618eb75d7fb9497df6ad02b984e46b857855d03161922R13