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

Condense list of "available when" constraints #625

Open
1 of 2 tasks
dimitribouniol opened this issue Jun 14, 2023 · 0 comments
Open
1 of 2 tasks

Condense list of "available when" constraints #625

dimitribouniol opened this issue Jun 14, 2023 · 0 comments
Labels
enhancement Improvements or enhancements to existing functionality

Comments

@dimitribouniol
Copy link

dimitribouniol commented Jun 14, 2023

Description

When a type has a complex set of generics and constraints on those generics, a single relevant constraint on a method can really be lost in the generated documentation. For instance, in the example below, the only meaningful constraint for this method is in the extension's where clause: AccessMode == ReadWrite. However, the documentation insists on expanding the main type's constraints as well:

public actor Datastore<
    Version: RawRepresentable & Hashable & CaseIterable,
    CodedType: Codable,
    IdentifierType: Indexable,
    AccessMode: _AccessMode
> where Version.RawValue: Indexable & Comparable { ...
image

Checklist

  • If possible, I've reproduced the issue using the main branch of this package.
  • This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

"Available when" lists only AccessMode == ReadWrite.

Actual behavior

"Available when" lists the constraints of the entire type, which should have already been met by the time the user calls this method being documented. If the constraints need to me mentioned (in the case of a static method, for instance, as they inform the resulting type), they should at least be in a more consumable format, perhaps a bulleted list, or in a more concise blurb listing easy "source" type once?

ie. instead of:

Available when Version conforms to CaseIterable, Version conforms to Hashable, Version conforms to RawRepresentable, CodedType conforms to Decodable, CodedType conforms to Encodable, IdentifierType conforms to Comparable, IdentifierType conforms to Decodable, IdentifierType conforms to Encodable, AccessMode is ReadWrite, Version.RawValue conforms to Comparable, Version.RawValue conforms to Decodable, and Version.RawValue conforms to Encodable.

show:

Available when Version conforms to CaseIterable, Hashable, and RawRepresentable; CodedType conforms to Decodable, and Encodable; IdentifierType conforms to Comparable, Decodable, and Encodable; AccessMode is ReadWrite; and Version.RawValue conforms to Comparable, Decodable, and Encodable.

Better, list these in alphabetical order?

Available when AccessMode is ReadWrite; CodedType conforms to Decodable, and Encodable; IdentifierType conforms to Comparable, Decodable, and Encodable; Version conforms to CaseIterable, Hashable, and RawRepresentable; and Version.RawValue conforms to Comparable, Decodable, and Encodable.

Steps To Reproduce

No response

Swift-DocC Version Information

Version shipping in Xcode 15 beta 1

Swift Compiler Version Information

Apple Swift version 5.9 (swiftlang-5.9.0.114.6 clang-1500.0.27.1)
Target: arm64-apple-macosx13.0
@dimitribouniol dimitribouniol added the bug Something isn't working label Jun 14, 2023
@d-ronnqvist d-ronnqvist added enhancement Improvements or enhancements to existing functionality and removed bug Something isn't working labels Dec 21, 2023
@d-ronnqvist d-ronnqvist changed the title The "available when" constraints list too much for complex types Condense list of "available when" constraints Dec 21, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improvements or enhancements to existing functionality
Projects
None yet
Development

No branches or pull requests

2 participants