Add documentation for syntax nodes and their children

[ahoppen]

SwiftSyntax’s nodes are currently mostly lacking any documentation. It would be a great community effort to add a description to to every node and every child. Writing documentation for some nodes and children will be easier than for other. The expectation is that if there are any non-obvious things to point out, the documentation should do so. I am happy to help if the semantics of a node or a child are not clear.

To make sure we don’t have multiple PRs adding documentation for the same node please add a comment to this issue with the node(s) you are working on. If you have commit access to this repository, you can also assign a node modify the issue and assign a node to yourself by marking it as ticked and adding your name behind it.

#1527 contains an example of how the documentation of a syntax node could look like.

• AccessorBlockSyntax
• AccessorDeclSyntax
• AccessorEffectSpecifiersSyntax
• AccessorParameterSyntax
• AccessPathComponentSyntax
• ActorDeclSyntax
• ArrayElementSyntax
• ArrayExprSyntax
• ArrayTypeSyntax
• ArrowExprSyntax
• AsExprSyntax
• AssignmentExprSyntax
• AssociatedtypeDeclSyntax @whiteio
• AttributedTypeSyntax
• AttributeSyntax
• AvailabilityArgumentSyntax
• AvailabilityConditionSyntax
• AvailabilityEntrySyntax
• AvailabilityLabeledArgumentSyntax
• AvailabilityVersionRestrictionListEntrySyntax
• AvailabilityVersionRestrictionSyntax
• AwaitExprSyntax
• BackDeployedAttributeSpecListSyntax
• BinaryOperatorExprSyntax
• BooleanLiteralExprSyntax
• BorrowExprSyntax
• BreakStmtSyntax
• CaseItemSyntax
• CatchClauseSyntax
• CatchItemSyntax
• ClassDeclSyntax @whiteio
• ClassRestrictionTypeSyntax
• ClosureCaptureItemSpecifierSyntax
• ClosureCaptureItemSyntax
• ClosureCaptureSignatureSyntax
• ClosureExprSyntax
• ClosureParameterClauseSyntax
• ClosureParameterSyntax
• ClosureParamSyntax
• ClosureSignatureSyntax
• CodeBlockItemSyntax
• CodeBlockSyntax
• CompositionTypeElementSyntax
• CompositionTypeSyntax
• ConditionElementSyntax
• ConformanceRequirementSyntax @andrewjl
• ConstrainedSugarTypeSyntax
• ContinueStmtSyntax
• ConventionAttributeArgumentsSyntax
• ConventionWitnessMethodAttributeArgumentsSyntax
• DeclModifierDetailSyntax
• DeclModifierSyntax
• DeclNameArgumentsSyntax
• DeclNameArgumentSyntax
• DeclNameSyntax
• DeferStmtSyntax
• DeinitializerDeclSyntax @whiteio
• DerivativeRegistrationAttributeArgumentsSyntax
• DesignatedTypeElementSyntax
• DictionaryElementSyntax
• DictionaryExprSyntax
• DictionaryTypeSyntax
• DifferentiabilityParamsClauseSyntax
• DifferentiabilityParamsSyntax
• DifferentiabilityParamSyntax
• DifferentiableAttributeArgumentsSyntax
• DiscardAssignmentExprSyntax
• DocumentationAttributeArgumentSyntax
• DoStmtSyntax
• DynamicReplacementArgumentsSyntax
• EditorPlaceholderDeclSyntax
• EditorPlaceholderExprSyntax
• EnumCaseDeclSyntax
• EnumCaseElementSyntax
• EnumCaseParameterClauseSyntax
• EnumCaseParameterSyntax
• EnumDeclSyntax @andrewjl
• ExposeAttributeArgumentsSyntax
• ExpressionPatternSyntax
• ExpressionSegmentSyntax
• ExpressionStmtSyntax
• ExtensionDeclSyntax
• FallthroughStmtSyntax
• FloatLiteralExprSyntax
• ForcedValueExprSyntax
• ForgetStmtSyntax
• ForInStmtSyntax
• FunctionCallExprSyntax
• FunctionDeclSyntax
• FunctionEffectSpecifiersSyntax
• FunctionParameterSyntax
• FunctionSignatureSyntax
• FunctionTypeSyntax
• GenericArgumentClauseSyntax @andrewjl
• GenericArgumentSyntax @andrewjl
• GenericParameterClauseSyntax @andrewjl
• GenericParameterSyntax @andrewjl
• GenericRequirementSyntax @andrewjl
• GenericWhereClauseSyntax @andrewjl
• GuardStmtSyntax
• IdentifierExprSyntax
• IdentifierPatternSyntax
• IfConfigClauseSyntax
• IfConfigDeclSyntax
• IfExprSyntax
• ImplementsAttributeArgumentsSyntax
• ImplicitlyUnwrappedOptionalTypeSyntax
• ImportDeclSyntax @whiteio
• InfixOperatorExprSyntax
• InheritedTypeSyntax
• InitializerClauseSyntax
• InitializerDeclSyntax @ahoppen
• InOutExprSyntax
• IntegerLiteralExprSyntax
• IsExprSyntax @whiteio
• IsTypePatternSyntax
• KeyPathComponentSyntax
• KeyPathExprSyntax
• KeyPathOptionalComponentSyntax
• KeyPathPropertyComponentSyntax
• KeyPathSubscriptComponentSyntax
• LabeledSpecializeEntrySyntax
• LabeledStmtSyntax
• LayoutRequirementSyntax @andrewjl
• MacroDeclSyntax
• MacroExpansionDeclSyntax
• MacroExpansionExprSyntax
• MatchingPatternConditionSyntax
• MemberAccessExprSyntax
• MemberDeclBlockSyntax
• MemberDeclListItemSyntax
• MemberTypeIdentifierSyntax
• MetatypeTypeSyntax
• MissingDeclSyntax
• MissingExprSyntax
• MissingPatternSyntax
• MissingStmtSyntax
• MissingSyntax
• MissingTypeSyntax
• MoveExprSyntax
• MultipleTrailingClosureElementSyntax
• NamedOpaqueReturnTypeSyntax
• NilLiteralExprSyntax
• ObjCSelectorPieceSyntax
• OpaqueReturnTypeOfAttributeArgumentsSyntax
• OperatorDeclSyntax
• OperatorPrecedenceAndTypesSyntax
• OptionalBindingConditionSyntax
• OptionalChainingExprSyntax
• OptionalTypeSyntax
• OriginallyDefinedInArgumentsSyntax
• PackElementExprSyntax
• PackExpansionExprSyntax
• PackExpansionTypeSyntax
• PackReferenceTypeSyntax
• ParameterClauseSyntax
• PatternBindingSyntax
• PostfixIfConfigExprSyntax
• PostfixUnaryExprSyntax
• PoundSourceLocationArgsSyntax
• PoundSourceLocationSyntax
• PrecedenceGroupAssignmentSyntax
• PrecedenceGroupAssociativitySyntax
• PrecedenceGroupDeclSyntax
• PrecedenceGroupNameElementSyntax
• PrecedenceGroupRelationSyntax
• PrefixOperatorExprSyntax
• PrimaryAssociatedTypeClauseSyntax
• PrimaryAssociatedTypeSyntax
• ProtocolDeclSyntax @whiteio
• QualifiedDeclNameSyntax
• RegexLiteralExprSyntax
• RepeatWhileStmtSyntax
• ReturnClauseSyntax
• ReturnStmtSyntax
• SameTypeRequirementSyntax @andrewjl
• SequenceExprSyntax
• SimpleTypeIdentifierSyntax
• SourceFileSyntax
• SpecializeExprSyntax
• StringLiteralExprSyntax
• StringSegmentSyntax
• StructDeclSyntax @andrewjl
• SubscriptDeclSyntax
• SubscriptExprSyntax
• SuperRefExprSyntax
• SwitchCaseLabelSyntax
• SwitchCaseSyntax
• SwitchDefaultLabelSyntax
• SwitchExprSyntax
• TargetFunctionEntrySyntax
• TernaryExprSyntax
• ThrowStmtSyntax
• TryExprSyntax
• TupleExprElementSyntax
• TupleExprSyntax
• TuplePatternElementSyntax
• TuplePatternSyntax
• TupleTypeElementSyntax
• TupleTypeSyntax
• TypealiasDeclSyntax
• TypeAnnotationSyntax
• TypeEffectSpecifiersSyntax
• TypeExprSyntax
• TypeInheritanceClauseSyntax
• TypeInitializerClauseSyntax
• UnavailableFromAsyncArgumentsSyntax
• UnderscorePrivateAttributeArgumentsSyntax
• UnresolvedAsExprSyntax
• UnresolvedIsExprSyntax
• UnresolvedPatternExprSyntax
• UnresolvedTernaryExprSyntax
• ValueBindingPatternSyntax
• VariableDeclSyntax
• VersionTupleSyntax
• WhereClauseSyntax
• WhileStmtSyntax
• WildcardPatternSyntax
• YieldExprListElementSyntax
• YieldListSyntax
• YieldStmtSyntax

[ahoppen]

rdar://107972861

[andrewjl]

I'd like to grab some

• ConformanceRequirementSyntax
• EnumDeclSyntax
• GenericArgumentClauseSyntax
• GenericArgumentSyntax
• GenericParameterClauseSyntax
• GenericParameterSyntax
• GenericRequirementSyntax
• GenericWhereClauseSyntax
• LayoutRequirementSyntax
• SameTypeRequirementSyntax
• StructDeclSyntax

[whiteio]

Hey I'd like to work on these:

• ClassDeclSyntax
• DeinitializerDeclSyntax
• ImportDeclSyntax
• IsExprSyntax
• ProtocolDeclSyntax
• AssociatedtypeDeclSyntax

[dimsumthinking]

Of course it would be /will be great to have this level of documentation, but IMO what is also needed is a good old fashioned Technology Programming Guide that illustrates how one might accomplish some basic and common tasks. Otherwise it is difficult for folks that are new to the API (like me) to know where to begin or what is the idiomatic way to accomplish a task. I have learned so much from apple’s programming guides over the years.