Skip to content
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

Jump to bottom

Document fields #2123

Open
kddnewton opened this issue Jan 2, 2024 · 9 comments
Open

Document fields #2123

kddnewton opened this issue Jan 2, 2024 · 9 comments
Labels
good first issue Good for newcomers help wanted Extra attention is needed
Milestone
Long-term

Comments

@kddnewton
Copy link
Collaborator

kddnewton commented Jan 2, 2024 •
edited

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.

Importantly, we do not want to document any flags fields. These already have their own documentation on the flags itself, so we don't want to duplicate it.

  • 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
  • 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
@kddnewton kddnewton added good first issue Good for newcomers help wanted Extra attention is needed labels Jan 2, 2024
@kddnewton kddnewton pinned this issue Jan 2, 2024
@sanjaii
Copy link
Contributor

sanjaii commented Jan 3, 2024

Taking up IntegerNode

@sanjaii
Copy link
Contributor

sanjaii commented Jan 4, 2024

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

@matthew-healy
Copy link
Contributor

matthew-healy commented Jan 7, 2024 •
edited

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

@kddnewton
Copy link
Collaborator Author

@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.

dgollahon added a commit to dgollahon/prism that referenced this issue Jan 14, 2024
@dgollahon
Document IfNode fields
b1ca344 
- Adds documentation for the fields of the `IfNode`. Also updates the overall description to mention ternary expressions.
- Part of ruby#2123
@dgollahon dgollahon mentioned this issue Jan 14, 2024
Merged
@kddnewton kddnewton added this to the Ruby 3.4.0 milestone Jan 16, 2024
@MatheusRich
Copy link
Contributor

@kddnewton calling dibs on ArrayNode

@kddnewton
Copy link
Collaborator Author

@MatheusRich

@kddnewton calling dibs on ArrayNode

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

@MatheusRich
Copy link
Contributor

MatheusRich commented Jan 19, 2024 •
edited

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

PR: #2214

@MatheusRich
Copy link
Contributor

MatheusRich commented Jan 19, 2024 •
edited

Taking BreakNode now.

PR: #2216

@MatheusRich
Copy link
Contributor

Taking YieldNode now.

dgollahon added a commit to dgollahon/prism that referenced this issue Feb 1, 2024
@dgollahon
Document IfNode fields
86f0cf5 
- Adds documentation for the fields of the `IfNode`. Also updates the overall description to mention ternary expressions.
- Part of ruby#2123
dgollahon added a commit to dgollahon/prism that referenced this issue Feb 1, 2024
@dgollahon
Document IfNode fields
fd17c07 
- Adds documentation for the fields of the `IfNode`. Also updates the overall description to mention ternary expressions.
- Part of ruby#2123
@kddnewton kddnewton modified the milestones: CRuby unblocked, Long-term Feb 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Milestone
Long-term
Development

No branches or pull requests
4 participants
@kddnewton @matthew-healy @MatheusRich @sanjaii