docs: improve and fix public docs

[jeroen-meijer]

Status

READY

Breaking Changes

NO

Description

Problem

When projects that use this library have strict rules around documentation verification (for example, when checking docs in CI), this library makes that CI pipeline fail in some cases. When generating documentation for this library, some warnings arise such as invalid references to symbols ([Equatables] doesn't exist, but [Equatable] does). This might prevent the aforementioned libraries from getting their docs generated once uploaded to pub.dev.

An example of this behavior can be found on the score page of my package KanaKit.

10 points are deducted from the score, no docs are generated and the following warnings are given:

  warning: unresolved doc reference [Equatables]
    from kana_kit.KanaKitConfig.props: (file:///tmp/pub-dartlang-dartdocHOHOHD/pkg/lib/src/models/kana_kit_config.dart:88:20)
    in documentation inherited from equatable.Equatable.props: (file:///tmp/pub-cache-dirFCNUXL/hosted/pub.dartlang.org/equatable-1.2.2/lib/src/equatable.dart:22:20)
  warning: unresolved doc reference [Equatables]
    from kana_kit.Romanization.props: (file:///tmp/pub-dartlang-dartdocHOHOHD/pkg/lib/src/models/romanization/romanization.dart:39:20)
    in documentation inherited from equatable.Equatable.props: (file:///tmp/pub-cache-dirFCNUXL/hosted/pub.dartlang.org/equatable-1.2.2/lib/src/equatable.dart:22:20)
found 2 warnings and 0 errors

Solution

This PR contains fixes for those references, along with some clarification and streamlining for different parts of the API.

Feel free to pick and choose which changes you'd like to keep.
Needless to say, I recommend pulling in the entire PR. 😉

Changes

• Clarified and streamlined all public-facing API documentation
• Fixed invalid references to internal and external classes, fields and functions

Todos

• Tests (N/A)
• Documentation
• Examples (N/A)

Impact to Remaining Code Base

This PR will affect:

• All public-facing documentation.

[felangel]

Thanks for the awesome PR! Changes look great 💯