Document fields

[kddnewton]

At the moment, our config.yml file has documentation for every node type in the syntax tree. However, there is little to no documentation for the individual fields on the nodes. This is a crucial piece of information for understanding how the nodes should be used and what they represent. Therefore, we would like to document each field on each node, and surface that documentation to the end user.

This issue serves as a meta-issue for that work. Each node is listed below, and should be checked off when all of its fields are completely documented.

In terms of style we are very much not looking for "this is the receiver of the method call". Instead we are looking for "this can be nil or a node that represents a non-void expression". Generally we want to avoid tautological statements, and instead favor more useful comments. Examples are encouraged — where applicable — and should begin with 4 spaces. See

prism/config.yml

Lines 717 to 729 in c790abd

	comment: |
	The object that the method is being called on. This can be either
	`nil` or a node representing any kind of expression that returns a
	non-void value.
	foo.bar
	^^^
	+foo
	^^^
	foo + bar
	^^^

for an example.

• AliasGlobalVariableNode
• AliasMethodNode
• AlternationPatternNode
• AndNode
• ArgumentsNode
• ArrayNode
• ArrayPatternNode
• AssocNode
• AssocSplatNode
• BackReferenceReadNode
• BeginNode
• BlockArgumentNode
• BlockLocalVariableNode
• BlockNode
• BlockParameterNode
• BlockParametersNode
• BreakNode
• CallAndWriteNode
• CallNode
• CallOperatorWriteNode
• CallOrWriteNode
• CallTargetNode
• CapturePatternNode
• CaseMatchNode
• CaseNode
• ClassNode
• ClassVariableAndWriteNode
• ClassVariableOperatorWriteNode
• ClassVariableOrWriteNode
• ClassVariableReadNode
• ClassVariableTargetNode
• ClassVariableWriteNode
• ConstantAndWriteNode
• ConstantOperatorWriteNode
• ConstantOrWriteNode
• ConstantPathAndWriteNode
• ConstantPathNode
• ConstantPathOperatorWriteNode
• ConstantPathOrWriteNode
• ConstantPathTargetNode
• ConstantPathWriteNode
• ConstantReadNode
• ConstantTargetNode
• ConstantWriteNode
• DefNode
• DefinedNode
• ElseNode
• EmbeddedStatementsNode
• EmbeddedVariableNode
• EnsureNode
• FalseNode
• FindPatternNode
• FlipFlopNode
• FloatNode
• ForNode
• ForwardingArgumentsNode
• ForwardingParameterNode
• ForwardingSuperNode
• GlobalVariableAndWriteNode
• GlobalVariableOperatorWriteNode
• GlobalVariableOrWriteNode
• GlobalVariableReadNode
• GlobalVariableTargetNode
• GlobalVariableWriteNode
• HashNode
• HashPatternNode
• IfNode
• ImaginaryNode
• ImplicitNode
• ImplicitRestNode
• InNode
• IndexAndWriteNode
• IndexOperatorWriteNode
• IndexOrWriteNode
• IndexTargetNode
• InstanceVariableAndWriteNode
• InstanceVariableOperatorWriteNode
• InstanceVariableOrWriteNode
• InstanceVariableReadNode
• InstanceVariableTargetNode
• InstanceVariableWriteNode
• IntegerNode
• InterpolatedMatchLastLineNode
• InterpolatedRegularExpressionNode
• InterpolatedStringNode
• InterpolatedSymbolNode
• InterpolatedXStringNode
• ItLocalVariableReadNode
• ItParametersNode
• KeywordHashNode
• KeywordRestParameterNode
• LambdaNode
• LocalVariableAndWriteNode
• LocalVariableOperatorWriteNode
• LocalVariableOrWriteNode
• LocalVariableReadNode
• LocalVariableTargetNode
• LocalVariableWriteNode
• MatchLastLineNode
• MatchPredicateNode
• MatchRequiredNode
• MatchWriteNode
• MissingNode
• ModuleNode
• MultiTargetNode
• MultiWriteNode
• NextNode
• NilNode
• NoKeywordsParameterNode
• NumberedParametersNode
• NumberedReferenceReadNode
• OptionalKeywordParameterNode
• OptionalParameterNode
• OrNode
• ParametersNode
• ParenthesesNode
• PinnedExpressionNode
• PinnedVariableNode
• PostExecutionNode
• PreExecutionNode
• ProgramNode
• RangeNode
• RationalNode
• RedoNode
• RegularExpressionNode
• RequiredKeywordParameterNode
• RequiredParameterNode
• RescueModifierNode
• RescueNode
• RestParameterNode
• RetryNode
• ReturnNode
• SelfNode
• ShareableConstantNode
• SingletonClassNode
• SourceEncodingNode
• SourceFileNode
• SourceLineNode
• SplatNode
• StatementsNode
• StringNode
• SuperNode
• SymbolNode
• TrueNode
• UndefNode
• UnlessNode
• UntilNode
• WhenNode
• WhileNode
• XStringNode
• YieldNode

For determining which are documented, run:

require "yaml"
YAML.safe_load_file("config.yml").fetch("nodes").each do |node|
  status = node.fetch("fields", []).any? { |field| !field.key?("comment") } ? " " : "x"
  name = node.fetch("name")
  puts "- [#{status}] #{name}"
end

[sanjaii]

Taking up IntegerNode

[sanjaii]

@kddnewton We can actually mark the nodes which doesn't have any fields as done right?

[matthew-healy]

For visibility, I've opened #2135 which adds documentation for fields on HashNode, AssocNode and AssocSplatNode, and #2136 for RangeNode.

[kddnewton]

@kddnewton We can actually mark the nodes which doesn't have any fields as done right?

Yes you're right, I just marked them all as completed.

[MatheusRich]

@kddnewton calling dibs on ArrayNode

[kddnewton]

@MatheusRich

@kddnewton calling dibs on ArrayNode

That one already has an open PR. But the others should be good!

[MatheusRich]

Should've looked at the PRs too. Taking UnlessNode instead, then.

PR: #2214

[MatheusRich]

Taking BreakNode now.

PR: #2216

[MatheusRich]

Taking YieldNode now.