You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
"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
The text was updated successfully, but these errors were encountered:
d-ronnqvist
changed the title
The "available when" constraints list too much for complex types
Condense list of "available when" constraints
Dec 21, 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:Checklist
main
branch of this package.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:
show:
Better, list these in alphabetical order?
Steps To Reproduce
No response
Swift-DocC Version Information
Version shipping in Xcode 15 beta 1
Swift Compiler Version Information
The text was updated successfully, but these errors were encountered: