search

swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.2k stars 127 forks source link

Maintain enum order #401

Open nashysolutions opened 2 years ago

nashysolutions commented 2 years ago

Feature Name

Enum Sorting

Description

The enum cases are listed in the documentation in the order in which they are specified.

Motivation

I am documenting a package that calculates a poker hand from a selection of playing cards, and I have a list of possible hands declared as an enum.

I have purposely listed the hands in order of rank, because it reads better (no other reason).

public enum Hand {

    /// A single card with the highest available rank.
    case highCard(Rank)

    /// Two cards with matching rank.
    case pair(Rank)

    /// A combination of four cards, constituting of two ``pair(_:)`` hands.
    case twoPair(Rank)

    /// Three cards with matching rank.
    case threeKind(Rank)

    /// Five cards in a contiguous sequence of rank.
    case straight(Rank)

    /// Four cards with matching rank.
    case fourKind(Rank)

    /// Five cards with matching suite.
    case flush(Rank)

    /// A combination of five cards, constituting of a ``pair(_:)`` hand and a ``threeKind(_:)`` hand.
    case fullHouse(Rank)

    /// A combination of five cards, constituting of a ``straight(_:)`` hand and a ``flush(_:)`` hand.
    case straightFlush(Rank)

    /// A combination of five cards, constituting of a ``straight(_:)`` hand that has the highest possible rank and a ``flush(_:)`` hand.
    case royalFlush
}

It would be nice if that order was maintained in the documentation.

Screenshot 2022-10-09 at 07 20 01

Importance

Not important.

Alternatives Considered

No idea.

franklinsch commented 2 years ago

Thanks for filing @nashysolutions! This is related to https://github.com/apple/swift-docc/issues/340#issuecomment-1197593562. Did you have thoughts on the Markdown syntax you'd use to opt into this behavior? Using the new @Options/@GlobalOptions directives could make sense: https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#options-1. A good next step here would be to create a small pitch in the forums for further discussion.