Skip to content

Style guide updates for swift-testing #552

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 4 commits into from
Jul 22, 2024
Merged

Style guide updates for swift-testing #552

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e2d22b7
Updated the copyright years
Jul 18, 2024
650cbcc
Edits
Jul 18, 2024
dbe128b
Edits and added guidance on abstracts
Jul 18, 2024
a95501e
Changed “adhere” back to “adheres”
Jul 18, 2024
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
105 changes: 70 additions & 35 deletions Documentation/StyleGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<!--
This source file is part of the Swift.org open source project

Copyright (c) 2023 Apple Inc. and the Swift project authors
Copyright (c) 2023-2024 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
Expand All @@ -25,13 +25,13 @@ it have a consistent experience.
#### Indentation and spacing

When writing code for the testing library, use two spaces for indentation. Wrap
comments (especially long block comments) at 80 columns. Code does not need to
be wrapped at 80 columns, however it is recommended that long argument lists be
broken up across multiple lines if doing so improves readability.
comments (especially long block comments) at 80 columns. Code doesn't need to
be wrapped at 80 columns, however, it's recommended that you break up long
argument lists up across multiple lines if doing so improves readability.

#### Symbol names and API design

New API should follow the rules documented in Swift's
New API should follow the rules documented in the Swift
[API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).

Swift symbols that, for technical reasons, must be `public` but which are not
Expand Down Expand Up @@ -71,24 +71,59 @@ typedef struct SWTContainer {
#### Documenting symbols

Most symbols, including symbols marked `private`, should be given markup-style
documentation. Symbols that fulfill protocol requirements do not need to be
documentation. Symbols that fulfill protocol requirements don't need to be
given additional documentation (the documentation in the protocol declaration is
generally sufficient.)

When writing an abstract for a symbol, start the abstract with either a noun or
a verb ending in "s" depending on what kind of symbol it is:

| Noun | Verb ending in _s_ |
|----------------------|---------------------------|
| Associated type | Enumerations |
| Class | Function and function macro |
| Constant | Initializer |
| Enumerated types | Macro |
| Property | Method |
| Protocol | Subscript |
| Structure | |
| Type alias | |
| Variable | |
generally sufficient).

When writing an symbol abstracts, follow these general guidelines:

**Limit abstracts to a single sentence that's 150 characters or fewer.**
Abstracts consist of a single sentence or sentence fragment. Move any additional
information or explanation to other sections, such as the Overview (for
articles, classes, protocols, structures) or the Discussion (for methods,
properties, constants).

**Don't repeat the technical terms in an entity's name.** Abstracts are concise
but descriptive, and provide more information than a simple repetition of the
symbol name.

**Don't include links to other symbols in the abstract.** Avoid making the
reader leave the abstract to investigate terms. Provide links to other symbols
in the Overview, Discussion, See Also, or other sections.

**Don't include symbol names or technical terms in code font.** Use “plain
English” rather than the literal names to describe symbols. Specify the related
symbols in the Overview, Discussion, or other sections.

**Avoid parentheses or slashes in abstracts.** Don't add alternative versions of
terms or parenthetical asides in an abstract. If a task or topic requires
explanation, include the information in the Overview or Discussion. Acronyms are
an exception; spell out the full name on first use and include the acronym in
parentheses, such as: *Your computer can transfer information to devices that
use Bluetooth Low Energy (BLE) wireless technology.*

**Avoid language like *the following* or *below* or *these
examples* in your abstract.** Abstracts can appear without context in a search
result, so locational modifiers can be confusing.

**Use the correct grammatical style for the symbol.** Abstracts start
with a noun phrase or a verb phrase --- either a verb ending in *s* or an
imperative statement that conveys the symbol's action. Refer to the following
table when constructing your abstract:

| Noun | Imperative verb | Verb ending in *s* |
|----------------------|-----------------------|---------------------------|
| Associated type | API collection pages | Enumerations |
| Class | Articles | Function and function macro |
| Constant | Sample code projects | Initializer |
| Entitlement | | Macro |
| Enumerated types | | Method |
| Information property list key | | Notification |
| Property | | Subscript |
| Protocol | | |
| Structure | | |
| Type alias | | |
| Variable | | |

For instance, when writing the abstract for a class `Order`, you could write:

Expand Down Expand Up @@ -143,7 +178,7 @@ Documentation should be written in a professional voice. The author and the
reader are not expected to know each other personally, so avoid overly familiar
terms or colloquialisms such as _we_, _our_, or _let's_.

When writing specific instructions that a reader must follow exactly in order to
When writing specific instructions that a reader must follow exactly to
accomplish a task, use the second person (_you_, _your_, and so on).

#### Articles
Expand All @@ -160,23 +195,23 @@ these guidelines when creating an article:
- Start section headings with an imperative verb.
- Always follow a section heading with some text to setup the code or problem
you want to solve.
- Ensure that your filename adheres to the guidance in the [Filenames](#filenames)
section, below.
- Ensure that your filename adheres to the guidance in the
[Filenames](#filenames) section, below.

#### API collections

To organize related subsets of symbols, articles, and other content, use an API
collection. Follow these guidelines when creating an API collection:

- Begin the collection title with a noun that describes what the items in the
collection have in common.
- After the title, include a single sentence that describes the items in the
collection.
- Begin the collection title with a noun that describes what the items in the
collection have in common.
- After the title, include a single sentence abstract that describes the items
in the collection.
- Optionally, include an overview to the collection.
- Organize the symbols under topic group headings. Begin a topic group heading
with a gerund.
- Ensure that your filename adheres to the guidance in the [Filenames](#filenames)
section, below.
with a gerund.
- Ensure that your filename adheres to the guidance in the
[Filenames](#filenames) section, below.

#### Filenames

Expand All @@ -193,7 +228,7 @@ page is _Event tags_, the filename would be `event-tags.md`.
The DocC compiler lowercases URL paths, so filenames converted from
[UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case) may be difficult to
read. UpperCamelCase should still be used for Markdown files in the repository
such as this one that are not part of a DocC bundle.
such as this one that aren't part of a DocC bundle.

For more information, see [Adding Supplemental Content to a Documentation Catalog](https://www.swift.org/documentation/docc/adding-supplemental-content-to-a-documentation-catalog).

Expand All @@ -202,6 +237,6 @@ For more information, see [Adding Supplemental Content to a Documentation Catalo
Documentation is encoded as UTF-8 using Markdown where possible.

Documentation should be wrapped at 80 columns, including code samples in
documentation where possible, so the reader does not need to scroll
horizontally. If documentation includes a long link, it does not need to be
documentation where possible, so the reader doesn't need to scroll
horizontally. If documentation includes a long link, it doesn't need to be
split up over multiple lines, and a URL shortener should _not_ be used.