Skip to content

Commit df7cf79

Browse files
varungandhi-applevarungandhi-apple
authored
[docs] Add an index for the existing documentation. (swiftlang#32008)
1 parent f43a15e commit df7cf79

File tree

2 files changed

+323
-0
lines changed

2 files changed

+323
-0
lines changed

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@ Once you are able to build things successfully and have a compile-test-debug
8585
loop going, check out the [development tips](docs/DevelopmentTips.md) for
8686
better productivity while working on the compiler.
8787

88+
You can also skim [docs/README.md](/docs/README.md) to understand what
89+
high-level documentation is available.
90+
8891
### System Requirements
8992

9093
macOS, Ubuntu Linux LTS, and the latest Ubuntu Linux release are currently

‎docs/README.md

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
# Documentation Index
2+
3+
This page describes the overall organization of documentation for the Swift toolchain.
4+
It is divided into the following sections:
5+
6+
- [Tutorials](#tutorials)
7+
gently guide you towards achieving introductory tasks,
8+
while assuming minimal background knowledge.
9+
- [How-To Guides](#how-to-guides)
10+
help you complete specific tasks in a step-by-step fashion.
11+
- [Explanations](#explanations)
12+
discuss key subsystems and concepts, at a high level.
13+
They also provide background information and talk about design tradeoffs.
14+
- [Reference Guides](#reference-guides)
15+
contain a thorough technical reference for complex topics.
16+
They assume some overall understanding of surrounding subsystems.
17+
- [Recommended Practices](#recommended-practices)
18+
suggests guidelines for writing code and diagnostics.
19+
- [Project Information](#project-information)
20+
tracks continuous integration (CI), branching and release history.
21+
- [Evolution Documents](#evolution-documents)
22+
includes proposals and manifestos for changes to Swift.
23+
- The [External Resources](#external-resources) section provides links to
24+
valuable discussions about Swift development, in the form of talks
25+
and blog posts.
26+
- The [Uncategorized](#uncategorized) section is for documentation which does
27+
not fit neatly into any of the above categories. We would like minimize
28+
items in this section; avoid adding new documentation here.
29+
30+
Sometimes documentation is not enough.
31+
Especially if you are a new contributor, you might run into roadblocks
32+
which are not addressed by the existing documentation.
33+
Or they are addressed somewhere but you cannot find the relevant bits.
34+
If you are stuck, please use the [development category][] on the Swift forums
35+
to ask for help!
36+
37+
Lastly, note that we are slowly moving towards a more structured form of
38+
documentation, inspired by the Django project [[1][Django-docs-1]]
39+
[[2][Django-docs-2]]. Hence parts of this page are aspirational
40+
and do not reflect how much of the existing documentation is written.
41+
Pull requests to clean up the [Uncategorized](#uncategorized) section,
42+
or generally fill gaps in the documentation are very welcome.
43+
If you would like to make major changes, such as adding entire new pieces of
44+
documentation, please create a thread on the Swift forums under the
45+
[development category][] to discuss your proposed changes.
46+
47+
[development category]: https://forums.swift.org/c/development
48+
[Django-docs-1]: https://docs.djangoproject.com/
49+
[Django-docs-2]: https://documentation.divio.com/#the-documentation-system
50+
51+
## Tutorials
52+
53+
- [libFuzzerIntegration.md](/docs/libFuzzerIntegration.md):
54+
Using `libFuzzer` to fuzz Swift code.
55+
56+
## How-To Guides
57+
58+
- [DebuggingTheCompiler.md](/docs/DebuggingTheCompiler.md):
59+
Describes a variety of techniques for debugging.
60+
- Building for Android:
61+
- [Android.md](/docs/Android.md):
62+
How to run some simple programs and the Swift test suite on an Android device.
63+
- [AndroidBuild.md](/docs/AndroidBuild.md):
64+
How to build the Swift SDK for Android on Windows.
65+
- Building for Windows:
66+
- [Windows.md](/docs/Windows.md):
67+
Overview on how to build Swift for Windows.
68+
- [WindowsBuild.md](/docs/WindowsBuild.md):
69+
How to build Swift on Windows using Visual Studio.
70+
- [WindowsCrossCompile.md](/docs/WindowsCrossCompile.md):
71+
How to cross compile Swift for Windows on a non-Windows host OS.
72+
73+
## Explanations
74+
75+
- [ByteTree.md](/docs/ByteTree.md):
76+
Describes the ByteTree binary format used for serializing syntax trees
77+
in `libSyntax`.
78+
79+
### Compiler and Runtime Subsystems
80+
81+
- Driver:
82+
- [Driver.md](/docs/Driver.md):
83+
Provides an overview of the driver, compilation model, and the compiler's
84+
command-line options. Useful for integration into build systems other than
85+
SwiftPM or Xcode.
86+
- [DriverInternals.md](/docs/DriverInternals.md):
87+
Provides a bird's eye view of the driver's implementation.
88+
<!-- NOTE: Outdated -->
89+
- [DependencyAnalysis.md](/docs/DependencyAnalysis.md):
90+
Describes different kinds of dependencies across files in the same module,
91+
important for understanding incremental builds.
92+
- C and ObjC interoperability: Clang Importer and PrintAsObjC
93+
- [CToSwiftNameTranslation.md](/docs/CToSwiftNameTranslation.md):
94+
Describes how C and ObjC entities are imported into Swift
95+
by the Clang Importer.
96+
- [CToSwiftNameTranslation-OmitNeedlessWords.md](/docs/CToSwiftNameTranslation-OmitNeedlessWords.md):
97+
Describes how the "Omit Needless Words" algorithm works,
98+
making imported names more idiomatic.
99+
- Type-checking and inference:
100+
- [TypeChecker.rst](/docs/TypeChecker.rst):
101+
Provides an overview of how type-checking and inference work.
102+
- [RequestEvaluator.md](/docs/RequestEvaluator.md):
103+
Describes the request evaluator architecture, which is used for
104+
lazy type-checking and efficient caching.
105+
- [Literal.md](/docs/Literal.md):
106+
Describes type-checking and inference specifically for literals.
107+
- [Serialization.rst](/docs/Serialization.rst):
108+
Gives an overview of the LLVM bitcode format used for swiftmodules.
109+
- [StableBitcode.md](/docs/StableBitcode.md):
110+
Describes how to maintain compatibility when changing the serialization
111+
format.
112+
- SIL and SIL Optimizations:
113+
- [SILProgrammersManual.md](/docs/SILProgrammersManual.md):
114+
Provides an overview of the implementation of SIL in the compiler.
115+
- [OptimizerDesign.md](/docs/OptimizerDesign.md):
116+
Describes the design of the optimizer pipeline.
117+
- [HighLevelSILOptimizations.rst](docs/HighLevelSILOptimizations.rst):
118+
Describes how the optimizer understands the semantics of high-level
119+
operations on currency data types and optimizes accordingly.
120+
Includes a thorough discussion of the `@_semantics` attribute.
121+
122+
### SourceKit subsystems
123+
124+
- [SwiftLocalRefactoring.md](/docs/refactoring/SwiftLocalRefactoring.md):
125+
Describes how refactorings work and how they can be tested.
126+
127+
### Language subsystems
128+
129+
- Swift's Object Model
130+
- [LogicalObjects.md]():
131+
Describes the differences between logical and physical objects and
132+
introduces materialization and writeback.
133+
- [MutationModel.rst]() <!--: NOTE: Outdated -->
134+
- [DocumentationComments.md](/docs/DocumentationComments.md):
135+
Describes the format of Swift's documentation markup, including
136+
specially-recognized sections.
137+
138+
### Stdlib Design
139+
140+
- [SequencesAndCollections.rst](/docs/SequencesAndCollections.rst):
141+
Provides background on the design of different collection-related protocols.
142+
- [StdlibRationales.rst](/docs/StdlibRationales.rst):
143+
Provides rationale for common questions/complaints regarding design decisions
144+
in the Swift stdlib.
145+
146+
## Reference Guides
147+
148+
- [DriverParseableOutput.md](/docs/DriverParseableOutput.md):
149+
Describes the output format of the driver's `-parseable-output` flag,
150+
which is suitable for consumption by editors and IDEs.
151+
- [ObjCInterop.md](/docs/ObjCInterop.md)
152+
Documents how Swift interoperates with ObjC code and the ObjC runtime.
153+
- [LibraryEvolution.rst](/docs/LibraryEvolution.rst):
154+
Specifies what changes can be made without breaking binary compatibility.
155+
- [SIL.rst](/docs/SIL.rst):
156+
Documents the Swift Intermediate Language (SIL).
157+
- [TransparentAttr.md](/docs/TransparentAttr.md):
158+
Documents the semantics of the `@_transparent` attribute.
159+
- [Runtime.md](/docs/Runtime.md):
160+
Describes the ABI interface to the Swift runtime.
161+
<!-- NOTE: Outdated -->
162+
- [Lexicon.md](/docs/Lexicon.md):
163+
Canonical reference for terminology used throughout the project.
164+
165+
## Recommended Practices
166+
167+
### Coding
168+
169+
- [AccessControlInStdlib.rst](/docs/AccessControlInStdlib.rst):
170+
Describes the policy for access control modifiers and related naming
171+
conventions in the stdlib.
172+
<!-- NOTE: Outdated -->
173+
- [IndexInvalidation.md](/docs/IndexInvalidation.md):
174+
Describes the expected behavior of indexing APIs exposed by the stdlib.
175+
- [StdlibAPIGuidelines.rst](/docs/StdlibAPIGuidelines.rst):
176+
Provides guidelines for designing stdlib APIs.
177+
<!-- NOTE: Outdated -->
178+
- [StandardLibraryProgrammersManual](/docs/StandardLibraryProgrammersManual.md):
179+
Provides guidelines for working code in the stdlib.
180+
- [OptimizationTips.rst](/docs/OptimizationTips.rst):
181+
Provides guidelines for writing high-performance Swift code.
182+
183+
### Diagnostics
184+
185+
## Project Information
186+
187+
- [Branches.md](/docs/Branches.md):
188+
Describes how different branches are setup and what the automerger does.
189+
- [ContinuousIntegration.md](ContinuousIntegration.md):
190+
Describes the continuous integration setup, including the `@swift_ci` bot.
191+
192+
## Evolution Documents
193+
194+
### Manifestos
195+
196+
- ABI Stability and Library Evolution
197+
- [ABIStabilityManifesto.md](/docs/ABIStabilityManifesto.md):
198+
Describes the goals and design for ABI stability.
199+
- [LibraryEvolutionManifesto.md](/docs/LibraryEvolutionManifesto.md):
200+
Describes the goals and design for Library Evolution.
201+
- [BuildManifesto.md](BuildManifesto.md):
202+
Provides an outline for modularizing the build system for the Swift toolchain.
203+
- [CppInteroperabilityManifesto.md](CppInteroperabilityManifesto.md):
204+
Describes the motivation and design for first-class Swift-C++ interoperability.
205+
- [DifferentiableProgramming.md](/docs/DifferentiableProgramming.md):
206+
Outlines a vision and design for first-class differentiable programming in Swift.
207+
- [GenericsManifesto.md](/docs/GenericsManifesto.md):
208+
Communicates a vision for making the generics system in Swift more powerful.
209+
- [OwnershipManifesto.md](/docs/OwnershipManifesto.md):
210+
Provides a framework for understanding ownership in Swift,
211+
and highlights potential future directions for the language.
212+
- [StringManifesto.md](/docs/StringManifesto.md):
213+
Provides a long-term vision for the `String` type.
214+
215+
### Proposals
216+
217+
Old proposals are present in the [/docs/proposals](/docs/proposals) directory.
218+
More recent proposals are located in the [apple/swift-evolution][] repository.
219+
You can see the status of different proposals at
220+
<https://apple.github.io/swift-evolution/>.
221+
222+
[swift-evolution]: https://github.com/apple/swift-evolution
223+
224+
### Surveys
225+
226+
- [ErrorHandlingRationale.rst](/docs/ErrorHandlingRationale.rst):
227+
Surveys error-handling in a variety of languages, and describes the rationale
228+
behind the design of error handling in Swift.
229+
- [weak.rst](/docs/weak.rst):
230+
Discusses weak references, including the designs in different languages,
231+
and proposes changes to Swift (pre-1.0).
232+
<!-- NOTE: Outdated -->
233+
234+
### Archive
235+
236+
These documents are known to be out-of-date and are superseded by other
237+
documentation, primarily [The Swift Programming Language (TSPL)][].
238+
They are preserved mostly for historical interest.
239+
240+
- [AccessControl.rst](/docs/AccessControl.swift)
241+
- [Arrays.rst](/docs/Arrays.rst)
242+
<!-- Has additional notes on bridging that may be of general interest? -->
243+
- [Generics.rst](/docs/Generics.rst)
244+
- [ErrorHandling.rst](/docs/ErrorHandling.rst)
245+
- [StringDesign.rst](/docs/StringDesign.rst)
246+
- [TextFormatting.rst](/docs/TextFormatting.rst)
247+
248+
[The Swift Programming Language]: https://docs.swift.org/swift-book
249+
250+
## External Resources
251+
252+
The official [Swift blog](https://swift.org/blog/) contains a lot of useful
253+
information, such as how library evolution works and how the compiler's new
254+
diagnostic architecture is structured, helping us provide more precise
255+
diagnostics.
256+
257+
TODO: Add a new document ExternalResources.md.
258+
259+
## Uncategorized
260+
261+
### Needs refactoring
262+
263+
The documents in this section might be worth breaking up into several documents,
264+
and linking one document from the other. Breaking up into components will
265+
provide greater clarity to contributors wanting to add new documentation.
266+
267+
- [ARCOptimization.rst](/docs/ARCOptimization.rst):
268+
Covers how ARC optimization works, with several examples.
269+
TODO: Not clear if this is intended to be an explanation or a reference guide.
270+
- [CompilerPerformance.md](/docs/CompilerPerformance.md):
271+
Thoroughly discusses different ways of measuring compiler performance
272+
and common pitfalls.
273+
TODO: Consider breaking up into one high-level explanation explaining key
274+
concepts and individual how-to guides that can be expanded independently.
275+
Also, it's not the right place to explain details of different compiler modes.
276+
- [DevelopmentTips.md](/docs/DevelopmentTips.md):
277+
Contains an assortment of tips for better productivity when working on the
278+
compiler.
279+
TODO: Might be worthwhile to make a dedicated how-to guide or explanation.
280+
It might also be valuable to introduce the tips in context, and have the
281+
explanation link to all the different tips.
282+
- [Diagnostics.md](/docs/Diagnostics.md):
283+
Describes how to write diagnostic messages and associated educational notes.
284+
TODO: Consider splitting into how-tos and recommended practices.
285+
For example, we could have a how-to guide on adding a new diagnostic,
286+
and have a recommended practices page which explains the writing style
287+
for diagnostics and educational notes.
288+
- [HowSwiftImportsCAPIs.md](/docs/HowSwiftImportsCAPIs.md):
289+
Contains a thorough description of the mapping between C/ObjC entities and
290+
Swift entities.
291+
TODO: Not clear if this is intended to be language documentation
292+
(for Swift developers), an explanation or a reference guide.
293+
- [OptimizerCountersAnalysis.md](/docs/OptimizerCountersAnalysis.md):
294+
TODO: Consider breaking up into a how-to guide
295+
on dumping and analyzing the counters
296+
and an explanation for the the counter collection system.
297+
- [Testing.md](/docs/Testing.md):
298+
TODO: Consider splitting into a how-to guide on writing a new test case
299+
and an explanation for how the compiler is tested.
300+
- [SwiftIndent.md](/docs/SwiftIndent.md):
301+
TODO: Unclear if this is intended to be an explanation or a reference guide.
302+
- [Random.md](/docs/Random.md): Stub.
303+
304+
### Archive
305+
306+
- [FailableInitializers.rst](/docs/FailableInitializers.rst):
307+
Superseded by documentation in [The Swift Programming Language][].
308+
- [InitializerProblems.rst](/docs/InitializerProblems.rst):
309+
Describes some complexities around initialization in Swift.
310+
TODO: It would be great to have an explanation, say `InitializationModel.md`,
311+
that covers the initialization model and new attributes like
312+
`@_hasMissingDesignatedInitializers`. Some of this is covered in
313+
[TSPL's initialization section][] but that doesn't include newly added
314+
attributes.
315+
- [Modules.rst](/docs/Module.rst): for Swift pre-1.0.
316+
- [Swift3Compatibility.md](/docs/Swift3Compatibility.md):
317+
Discusses the Swift 3 -> Swift 4 migration.
318+
- [StoredAndComputedVariables.rst](): for Swift pre-1.0.
319+
320+
[TSPL's initialization section]: https://docs.swift.org/swift-book/LanguageGuide/Initialization.html

0 commit comments

Comments
 (0)