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

[SR-3281] Update swift man page #10241

Merged
merged 1 commit into from Jun 27, 2017

Conversation

Projects
None yet
7 participants
@contraultra
Contributor

contraultra commented Jun 14, 2017

Attempt at SR-3281. (cc @CodaFi 😃)

Feedback is welcome.

NAME
    swift -- Safe, fast, and expressive general-purpose programming language

SYNOPSIS
    To invoke the Swift REPL (Read-Eval-Print-Loop):

        swift

    To execute a Swift program:

        swift program.swift -- <arguments>

    To work with the Swift Package Manager:

        swift build|package|run|test [options] <inputs>

    To invoke the Swift compiler:

        swiftc [options] <inputs>

    A list of supported options is available through the "-help" option:

        swift -help

        swift build -help

        swiftc -help

DESCRIPTION
    Swift is a general-purpose programming language built using a modern
    approach to safety, performance, and software design patterns.

    The goal of the Swift project is to create the best available language
    for uses ranging from systems programming, to mobile and desktop apps,
    scaling up to cloud services. Most importantly, Swift is designed to
    make writing and maintaining *correct* programs easier for the
    developer. To achieve this goal, we believe that the most obvious way to
    write Swift code must also be:

    Safe. The most obvious way to write code should also behave in a safe
    manner. Undefined behavior is the enemy of safety, and developer
    mistakes should be caught before software is in production. Opting for
    safety sometimes means Swift will feel strict, but we believe that
    clarity saves time in the long run.

    Fast. Swift is intended as a replacement for C-based languages (C, C++,
    and Objective-C). As such, Swift must be comparable to those languages
    in performance for most tasks. Performance must also be predictable and
    consistent, not just fast in short bursts that require clean-up later.
    There are lots of languages with novel features — being fast is rare.

    Expressive. Swift benefits from decades of advancement in computer
    science to offer syntax that is a joy to use, with modern features
    developers expect. But Swift is never done. We will monitor language
    advancements and embrace what works, continually evolving to make Swift
    even better.

BUGS
    Reporting bugs is a great way for anyone to help improve Swift. The bug
    tracker for Swift, an open-source project, is located at
    <https://bugs.swift.org>.

    If a bug can be reproduced only within an Xcode project or a playground,
    or if the bug is associated with an Apple NDA, please file a report to
    Apple’s bug reporter at <https://bugreport.apple.com> instead.

SEE ALSO
  HOME PAGE
    <https://swift.org>

  APPLE DEVELOPER RESOURCES
    <https://developer.apple.com/swift/resources>

  CODE REPOSITORIES
    Swift Programming Language at <https://github.com/apple/swift>

    Swift Package Manager at
    <https://github.com/apple/swift-package-manager>
@CodaFi

This comment has been minimized.

Show comment
Hide comment
@CodaFi

CodaFi Jun 14, 2017

Collaborator

Thank you for picking this up! 💖

You should notify swift-dev and maybe swift-evolution about this.

Collaborator

CodaFi commented Jun 14, 2017

Thank you for picking this up! 💖

You should notify swift-dev and maybe swift-evolution about this.

@DougGregor

Looks great, thank you!

Show outdated Hide outdated docs/tools/swift.pod Outdated
B<swift>
=back

This comment has been minimized.

@DougGregor

DougGregor Jun 14, 2017

Member

Maybe also add:

To execute a swift program:

swift program.swift -- <args>
@DougGregor

DougGregor Jun 14, 2017

Member

Maybe also add:

To execute a swift program:

swift program.swift -- <args>
@xwu

Great improvement, bravo for taking the time to put this together. I've gone into editor mode and made some nitpicky comments.

Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
The goal of the Swift project is to create the best available language for uses
ranging from systems programming, to mobile and desktop apps, scaling up to
cloud services. Most importantly, Swift is designed to make writing and
maintaining I<correct> programs easier for the developer. To achieve this goal,

This comment has been minimized.

@xwu

xwu Jun 14, 2017

Collaborator

I wonder if the text from "To achieve this goal..." to the end of this section is really doing much for the man page. I don't see other examples where this level of detail as to design intent is recorded in the "Description" section of other man pages.

@xwu

xwu Jun 14, 2017

Collaborator

I wonder if the text from "To achieve this goal..." to the end of this section is really doing much for the man page. I don't see other examples where this level of detail as to design intent is recorded in the "Description" section of other man pages.

This comment has been minimized.

@contraultra

contraultra Jun 14, 2017

Contributor

see RUBY(1) as an example. debatable, and based off @CodaFi's ideas.

@contraultra

contraultra Jun 14, 2017

Contributor

see RUBY(1) as an example. debatable, and based off @CodaFi's ideas.

This comment has been minimized.

@xwu

xwu Jun 14, 2017

Collaborator

Indeed, debatable.

Ruby does something quite different, however. It describes what the language is (e.g., garbage collected). This text here describes what the language should/must/will be (e.g., should be safe, will feel strict, must be comparable). It is a description of the Swift project, but not really a description of the Swift language.

@xwu

xwu Jun 14, 2017

Collaborator

Indeed, debatable.

Ruby does something quite different, however. It describes what the language is (e.g., garbage collected). This text here describes what the language should/must/will be (e.g., should be safe, will feel strict, must be comparable). It is a description of the Swift project, but not really a description of the Swift language.

safety, performance, and software design patterns.
The goal of the Swift project is to create the best available language for uses
ranging from systems programming, to mobile and desktop apps, scaling up to

This comment has been minimized.

@xwu

xwu Jun 14, 2017

Collaborator

Nit here: That comma between "programming" and "to mobile" shouldn't be there. I know you've transposed this text from elsewhere, but nonetheless it's an extraneous comma.

@xwu

xwu Jun 14, 2017

Collaborator

Nit here: That comma between "programming" and "to mobile" shouldn't be there. I know you've transposed this text from elsewhere, but nonetheless it's an extraneous comma.

Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
@dabrahams

This comment has been minimized.

Show comment
Hide comment
@dabrahams

dabrahams Jun 14, 2017

Member
Member

dabrahams commented Jun 14, 2017

@xwu

Just some straggling follow-on comments.

Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
@contraultra

This comment has been minimized.

Show comment
Hide comment
@contraultra

contraultra Jun 16, 2017

Contributor

The feedback period for this pull request attempt has ended.

Thank you to those who participated in the feedback. Based on the feedback received, I have included most suggestions and this is the final draft.

Please review.

Contributor

contraultra commented Jun 16, 2017

The feedback period for this pull request attempt has ended.

Thank you to those who participated in the feedback. Based on the feedback received, I have included most suggestions and this is the final draft.

Please review.

Show outdated Hide outdated docs/tools/swift.pod Outdated
@contraultra

This comment has been minimized.

Show comment
Hide comment
@contraultra

contraultra Jun 27, 2017

Contributor

Pinging @DougGregor, @CodaFi, or @adrian-prantl to review.
I hope this doesn't get buried...

Contributor

contraultra commented Jun 27, 2017

Pinging @DougGregor, @CodaFi, or @adrian-prantl to review.
I hope this doesn't get buried...

Show outdated Hide outdated docs/tools/swift.pod Outdated
Show outdated Hide outdated docs/tools/swift.pod Outdated
[SR-3281] Update swift man page
For future reference, please refer to the following man pages:

- PERLDOC(1)
- PERLPODSPEC(1)
- PODCHECKER(1)
@contraultra

This comment has been minimized.

Show comment
Hide comment
@contraultra

contraultra Jun 27, 2017

Contributor

@CodaFi, I've made changes based on your feedback.

Instead of

general-purpose programming language,

it's now

Safe, fast, and expressive general-purpose programming language.

Contributor

contraultra commented Jun 27, 2017

@CodaFi, I've made changes based on your feedback.

Instead of

general-purpose programming language,

it's now

Safe, fast, and expressive general-purpose programming language.

@CodaFi

This comment has been minimized.

Show comment
Hide comment
@CodaFi

CodaFi Jun 27, 2017

Collaborator

Beautiful.

I think this is light years ahead of what was here before.

⛵️

@swift-ci please smoke test and merge

Collaborator

CodaFi commented Jun 27, 2017

Beautiful.

I think this is light years ahead of what was here before.

⛵️

@swift-ci please smoke test and merge

@swift-ci swift-ci merged commit 6bf18ea into apple:master Jun 27, 2017

2 of 3 checks passed

Test and Merge (smoke test) Build started.
Details
Swift Test Linux Platform (smoke test)
Details
Swift Test OS X Platform (smoke test)
Details

@contraultra contraultra deleted the contraultra:SR-3281 branch Jun 27, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment