Merge pull request #1824 from ahoppen/ahoppen/glosssary

Add a glossary to SwiftSyntax

Author: ahoppen

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md

@@ -17,6 +17,7 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 ### Articles
 
 - <doc:Working-with-SwiftSyntax>
+- <doc:Glossary>
 
 ### Tutorials
 

Sources/SwiftSyntax/Documentation.docc/Glossary.md

@@ -0,0 +1,28 @@
+# Glossary
+
+Glossary of terms and abbreviations used in SwiftSyntax
+
+## Abbreviations and Terms
+
+To avoid ongoing repetition of common long terms, SwiftSyntax uses a couple of abbreviations that are common in compiler projects.
+
+
+**Arena** See ``SyntaxArena``
+
+**Decl** Abbreviation for *Declaration*
+
+**Expr** Abbreviation for *Expression*
+
+**Layout Node** A layout node has can have an arbitrary number of children and provides structure to the syntax tree. All ``Syntax`` nodes that aren’t ``TokenSyntax`` are layout nodes. For example a ``StructDeclSyntax`` consists of, among others, of the `struct` keyword, the name and the `memberBlock`. The latter is again a layout node that contains multiple children. Layout nodes never represent any source code in the syntax tree by themselves. All source code within the syntax tree is represented by *tokens*.
+
+**Node** A *layout node* or *token*
+
+**RawSyntax** The underlying storage of syntax nodes. These are manually memory managed inside an *arena*. You should not need to interact with them unless contributing to swift-syntax.
+
+**Stmt** Abbreviation for *Statement*
+
+**Token** See ``TokenSyntax``
+
+**Trivia** See ``Trivia``
+
+<!-- IMPORTANT: Please keep the list above alphabetically ordered instead of adding new entries at the bottom -->

Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md

@@ -17,6 +17,7 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 ### Articles
 
 - <doc:Working-with-SwiftSyntax>
+- <doc:Glossary>
 
 ### Tutorials
 

Sources/SwiftSyntax/TokenSyntax.swift

@@ -13,6 +13,13 @@
 // MARK: TokenSyntax
 
 /// A Syntax node representing a single token.
+///
+/// All source code of a syntax tree is represented by tokens – layout nodes
+/// never contain any source code by themselves.
+///
+/// A token consists of leading ``Trivia``, i.e. whitespaces before the actual
+/// token contents, the token’s `text` and trailing ``Trivia`` after the token’s
+/// content.
 public struct TokenSyntax: SyntaxProtocol, SyntaxHashable {
   /// The ``Syntax`` node that provides the underlying data.
   ///

Sources/SwiftSyntax/Trivia.swift

@@ -15,8 +15,18 @@ public enum TriviaPosition {
   case trailing
 }
 
-/// A collection of leading or trailing trivia. This is the main data structure
-/// for thinking about trivia.
+/// Trivia represent pieces of the source code that are not relevant to represent
+/// its semantic structure.
+///
+/// The standard examples of trivia are spaces, newlines and comments.
+///
+/// The SwiftSyntax tree retains trivia to maintain round-tripness of the source
+/// code, ensuring that printing the entire syntax tree be rendered back into
+/// text that is byte-for-byte identical to the original source.
+///
+/// Each ``TokenSyntax`` can have multiple ``TriviaPiece``s as either leading or
+/// trailing trivia, which occur before or after the token’s content, respectively.
+/// ``Trivia`` represents a collection of these ``TriviaPiece``s
 public struct Trivia {
   /// The pieces this trivia consists of. Each ``TriviaPiece`` can represent
   /// multiple characters, such as an entire comment or 4 spaces.