search

apple / swift-log

A Logging API for Swift
https://apple.github.io/swift-log/
Apache License 2.0
3.54k stars 294 forks source link

Generated documentation doesn't order the Log levels in source order, but alphabetizes them, which causes some confusion while reading it. #224

Closed heckj closed 2 years ago

heckj commented 2 years ago

Expected behavior

The generated Documentation (using DocC) describing the log levels would be ordered as they are in the source file

Actual behavior

The generated Documentation (using DocC) with swift-log presented the levels in alphabetical order

Screenshot attached

Screen Shot 2022-07-19 at 3 02 54 PM

the ordering of which doesn't match the expected ordering from the source:

I ran into this while working on a Vapor project, and realized the ordering in the generated DocC meant that the descriptions were very "out of whack" for reading with any intention of what the ordering SHOULD be.

swift-log doesn't currently have a DocC catalog - which is where you could put the explicit ordering for this sort of scenario, as least in the case of DocC generated content.

Steps to reproduce

  1. clone out swift-log
  2. open Package.swift (w/ Xcode)
  3. Product > Build Documentation
  4. view Logger > Logger.Level

If possible, minimal yet complete reproducer code (or URL to code)

main branch as well as the 1.4.2 branch of swift-log

SwiftLog version/commit hash

Swift & OS version (output of swift --version && uname -a)

swift-driver version: 1.60 Apple Swift version 5.7 (swiftlang-5.7.0.120.1 clang-1400.0.28.1)
Target: arm64-apple-macosx12.0
Darwin Sparrow.local 21.5.0 Darwin Kernel Version 21.5.0: Tue Apr 26 21:08:29 PDT 2022; root:xnu-8020.121.3~4/RELEASE_ARM64_T8101 arm64
ktoso commented 2 years ago

This sounds good, thanks for spotting it! Would be send in a PR please? Thanks in advance!

heckj commented 2 years ago

Absolutely, #225 up as the most minimal update that solves the issue.

ethan-kusters commented 2 years ago

@heckj if we don't have one already, I think this would be a good enhancement for DocC as well. DocC already has the line number information so there's no reason it couldn't sort by line number instead of alphabetically in situations like this.