better-define what it means to be undocumented vs documented #315

New issue

Open

opened 2025-10-14 15:59:29 -06:00 by navan · 0 comments

navan commented

2025-10-14 15:59:29 -06:00

Owner

Originally created by @tayloraswift on 12/26/2023

right now the documentation coverage metric is not as useful as it could be, and this is also having negative effects on the site’s ranking on google.

currently, in the eyes of the coverage metric, documentation is mandatory for all public API. but there are straightforward situations in which we should not include a symbol in the coverage denominator:

C symbols. most swift package authors do not document C API, and we should not expect them to.
trivial enum cases (cases with no associated values)

there are some more complex situations where the same reasoning should also apply

memberwise inits
static vars that return Self

but we don’t have a way to detect those yet.

*Originally created by @tayloraswift on 12/26/2023* right now the documentation coverage metric is not as useful as it could be, and this is also having negative effects on the site’s ranking on google. currently, in the eyes of the coverage metric, documentation is mandatory for all public API. but there are straightforward situations in which we should **not** include a symbol in the coverage denominator: - C symbols. most swift package authors do not document C API, and we should not expect them to. - trivial enum cases (cases with no associated values) there are some more complex situations where the same reasoning should also apply - memberwise inits - `static var`s that return `Self` but we don’t have a way to detect those yet.