Skip to content

Part 1 of the PackageDescription DocC documentation update #4276

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.

Sign up for GitHub

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

Merged
merged 18 commits into from
Apr 23, 2022
Merged

Part 1 of the PackageDescription DocC documentation update #4276

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
59b63a5
Part 1 of the documentation update.
Mar 30, 2022
4262d29
Corrected the docs for two `Package.Dependency` methods.
Apr 7, 2022
81ccd41
Changed the docs for the C language standards in response to PR comme…
Apr 7, 2022
4c2f9ce
Updated all the language standard identifier docs.
Apr 7, 2022
b0a7cca
More responses to comments on the PR.
Apr 7, 2022
7421574
Responded to more comments.
Apr 7, 2022
b84390f
Merge branch 'main' into zkiraly/documentation-update-1
zkiraly Apr 7, 2022
846916b
Some light editing of the DocC documentation.
Apr 20, 2022
405f3c1
More small edits.
Apr 20, 2022
32eddfd
More minor edits.
Apr 20, 2022
acc5ece
Merge branch 'main' into zkiraly/documentation-update-1
Apr 20, 2022
cd94221
Fixed a typo.
Apr 20, 2022
b6fc718
Removed unwanted blank-space.
Apr 22, 2022
105ba7f
Responding to Anders' notes.
Apr 22, 2022
44ba513
Merge branch 'apple:main' into zkiraly/documentation-update-1
zkiraly Apr 22, 2022
5feb566
I should not have touched this file, so I am reverting my changes there.
Apr 22, 2022
f2958b9
We can't link below the top level for legal reasons.
Apr 22, 2022
2b50fb8
A small editorial change.
Apr 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions Sources/PackageDescription/BuildSettings.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,17 +81,15 @@ public struct BuildSettingCondition: Encodable {

/// Creates a build setting condition.
///
/// - Parameters:
/// - platforms: The applicable platforms for this build setting condition.
/// - Parameter platforms: The applicable platforms for this build setting condition.
@available(_PackageDescription, introduced: 5.7)
public static func when(platforms: [Platform]) -> BuildSettingCondition {
BuildSettingCondition(platforms: platforms, config: .none)
}

/// Creates a build setting condition.
///
/// - Parameters:
/// - configuration: The applicable build configuration for this build setting condition.
/// - Parameter configuration: The applicable build configuration for this build setting condition.
@available(_PackageDescription, introduced: 5.7)
public static func when(configuration: BuildConfiguration) -> BuildSettingCondition {
BuildSettingCondition(platforms: .none, config: configuration)
Expand Down
8 changes: 5 additions & 3 deletions Sources/PackageDescription/Context.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,15 @@
//
//===----------------------------------------------------------------------===//

/// The context a Swift package is running in. This encapsulates states that are known at build-time.
/// For example where in the file system the current package resides.
/// The context information for a Swift package.
///
/// The context encapsulates states that are known when Swift Package Manager interprets the package manifest,
/// for example the location in the file system where the current package resides.
@available(_PackageDescription, introduced: 5.6)
public struct Context {
private static let model = try! ContextModel.decode()

/// The directory containing Package.swift.
/// The directory that contains `Package.swift`.
public static var packageDirectory : String {
model.packageDirectory
}
Expand Down
95 changes: 47 additions & 48 deletions Sources/PackageDescription/LanguageStandardSettings.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,161 +10,160 @@
//
//===----------------------------------------------------------------------===//

/// The supported C language standard to use for compiling C sources in the package.
///
/// Aliases are available for some C language standards. For example,
/// use `c89`, `c90`, or `iso9899_1990` for the "ISO C 1990" standard.
/// To learn more, read the [Clang Compiler User's Manual][1].
///
/// [1]: <https://clang.llvm.org/docs/UsersManual.html#differences-between-various-standard-modes>
/// The supported C language standard you use to compile C sources in the
/// package.
public enum CLanguageStandard: String, Encodable {

/// ISO C 1990.
/// The identifier for the ISO C 1990 language standard.
case c89

/// ISO C 1990.
/// The identifier for the ISO C 1990 language standard.
case c90

/// ISO C 1999.
/// The identifier for the ISO C 1999 language standard.
case c99

/// ISO C 2011.
/// The identifier for the ISO C 2011 language standard.
case c11

/// ISO C 2017.
/// The identifier for the ISO C 2017 language stadard.
@available(_PackageDescription, introduced: 5.4)
case c17

/// ISO C 2017.
/// The identifier for the ISO C 2017 language standard.
@available(_PackageDescription, introduced: 5.4)
case c18

/// Working Draft for ISO C2x.
/// The identifier for the ISO C2x draft language standard.
@available(_PackageDescription, introduced: 5.4)
case c2x

/// ISO C 1990 with GNU extensions.
/// The identifier for the ISO C 1990 language standard with GNU extensions.
case gnu89

/// ISO C 1990 with GNU extensions.
/// The identifier for the ISO C 1990 language standard with GNU extensions.
case gnu90

/// ISO C 1999 with GNU extensions.
/// The identifier for the ISO C 1999 language standard with GNU extensions.
case gnu99

/// ISO C 2011 with GNU extensions.
/// The identifier for the ISO C 2011 language standard with GNU extensions.
case gnu11

/// ISO C 2017 with GNU extensions.
/// The identifier for the ISO C 2017 language standard with GNU extensions.
@available(_PackageDescription, introduced: 5.4)
case gnu17

/// ISO C 2017 with GNU extensions.
/// The identifier for the ISO C 2017 language standard with GNU extensions.
@available(_PackageDescription, introduced: 5.4)
case gnu18

/// Working Draft for ISO C2x with GNU extensions.
/// The identifier for the ISO C2x draft language standard with GNU extensions.
@available(_PackageDescription, introduced: 5.4)
case gnu2x

/// ISO C 1990.
/// The identifier for the ISO C 1990 language standard.
case iso9899_1990 = "iso9899:1990"

/// ISO C 1990 with amendment 1.
/// The identifier for the ISO C 1990 language standard with amendment 1.
case iso9899_199409 = "iso9899:199409"

/// ISO C 1999.
/// The identifier for the ISO C 1999 language standard.
case iso9899_1999 = "iso9899:1999"

/// ISO C 2011.
/// The identifier for the ISO C 2011 language standard.
case iso9899_2011 = "iso9899:2011"

/// ISO C 2017.
/// The identifier for the ISO C 2017 language standard.
@available(_PackageDescription, introduced: 5.4)
case iso9899_2017 = "iso9899:2017"

/// ISO C 2017.
/// The identifier for the ISO C 2017 language standard.
@available(_PackageDescription, introduced: 5.4)
case iso9899_2018 = "iso9899:2018"
}

/// The supported C++ language standard to use for compiling C++ sources in the package.
/// The supported C++ language standard you use to compile C++ sources in the
/// package.
///
/// Aliases are available for some C++ language standards. For example,
/// use `cxx98` or `cxx03` for the "ISO C++ 1998 with amendments" standard.
/// To learn more, read the [C++ Support in Clang][1] status page.
///
/// [1]: <https://clang.llvm.org/cxx_status.html>
/// To learn more, see [C++ Support in Clang](https://clang.llvm.org/cxx_status.html).
public enum CXXLanguageStandard: String, Encodable {

/// ISO C++ 1998 with amendments.
/// The identifier for the ISO C++ 1998 language standard with amendments.
case cxx98 = "c++98"

/// ISO C++ 1998 with amendments.
/// The identifier for the ISO C++ 1998 language standard with amendments.
case cxx03 = "c++03"

/// ISO C++ 2011 with amendments.
/// The identifier for the ISO C++ 2011 language standard with amendments.
case cxx11 = "c++11"

/// ISO C++ 2014 with amendments.
/// The identifier for the ISO C++ 2014 language standard with amendments.
case cxx14 = "c++14"

/// ISO C++ 2017 with amendments.
/// The identifier for the ISO C++ 2017 language standard with amendments.
@available(_PackageDescription, introduced: 5.4)
case cxx17 = "c++17"

/// ISO C++ 2017 with amendments.
/// The identifier for the ISO C++ 2017 language standard with amendments.
@available(_PackageDescription, introduced: 4, deprecated: 5.4, renamed: "cxx17")
case cxx1z = "c++1z"

/// ISO C++ 2020 DIS.
/// The identifier for the ISO C++ 2020 language standard.
@available(_PackageDescription, introduced: 5.4)
case cxx20 = "c++20"

/// Working draft for ISO C++ 2023 DIS.
/// The identifier for the ISO C++ 2023 draft language standard.
@available(_PackageDescription, introduced: 5.6)
case cxx2b = "c++2b"

/// ISO C++ 1998 with amendments and GNU extensions.
/// The identifier for the ISO C++ 1998 language standard with amendments and GNU extensions.
case gnucxx98 = "gnu++98"

/// ISO C++ 1998 with amendments and GNU extensions.
/// The identifier for the ISO C++ 1998 language standard with amendments and GNU extensions.
case gnucxx03 = "gnu++03"

/// ISO C++ 2011 with amendments and GNU extensions.
/// The identifier for the ISO C++ 2011 language standard with amendments and GNU extensions.
case gnucxx11 = "gnu++11"

/// ISO C++ 2014 with amendments and GNU extensions.
/// The identifier for the ISO C++ 2014 language standard with amendments and GNU extensions.
case gnucxx14 = "gnu++14"

/// ISO C++ 2017 with amendments and GNU extensions.
/// The identifier for the ISO C++ 2017 language standard with amendments and GNU extensions.
@available(_PackageDescription, introduced: 5.4)
case gnucxx17 = "gnu++17"

/// ISO C++ 2017 with amendments and GNU extensions.
/// The identifier for the ISO C++ 2017 language standard with amendments and GNU extensions.
@available(_PackageDescription, introduced: 4, deprecated: 5.4, renamed: "gnucxx17")
case gnucxx1z = "gnu++1z"

/// ISO C++ 2020 DIS with GNU extensions.
/// The identifier for the ISO C++ 2020 language standard with GNU extensions.
@available(_PackageDescription, introduced: 5.4)
case gnucxx20 = "gnu++20"

/// Working draft for ISO C++ 2023 DIS with GNU extensions.
/// The identifier for the ISO C++ 2023 draft language standard with GNU extensions.
@available(_PackageDescription, introduced: 5.6)
case gnucxx2b = "gnu++2b"
}

/// The version of the Swift language to use for compiling Swift sources in the package.
/// The version of the Swift language you use to compile Swift sources in the
/// package.
public enum SwiftVersion {
/// The identifier for the Swift 3 language version.
@available(_PackageDescription, introduced: 4, obsoleted: 5)
case v3

/// The identifier for the Swift 4 language version.
@available(_PackageDescription, introduced: 4)
case v4

/// The identifier for the Swift 4.2 language version.
@available(_PackageDescription, introduced: 4)
case v4_2

/// The identifier for the Swift 5 language version.
Comment on lines +154 to +166
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, it's easier to read if the documentation for each case is just "Swift 3", "Swift 4.2", etc. Most likely, a user reading it already knows that the symbols are identifiers for Swift language versions, so it's probably better to avoid information overload.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do need a sentence fragment ending in a period, as described in the API Design Guidelines under "Write a Documentation Comment." So I will leave this as is.

@available(_PackageDescription, introduced: 5)
case v5

Expand Down
Loading