Skip to content

Commit 4ca49b4

Browse files
committed
Add some documentation strings to the parser code.
1 parent 336364c commit 4ca49b4

File tree

5 files changed

+158
-35
lines changed

5 files changed

+158
-35
lines changed

parser/src/ast.rs

Lines changed: 126 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
1-
//! Implement abstract syntax tree nodes for the python language.
1+
//! Implement abstract syntax tree (AST) nodes for the python language.
22
//!
3-
//! Roughly equivalent to this: https://docs.python.org/3/library/ast.html
3+
//! Roughly equivalent to [the python AST](https://docs.python.org/3/library/ast.html)
4+
//! Many AST nodes have a location attribute, to determine the sourcecode
5+
//! location of the node.
46
57
pub use crate::location::Location;
68
use num_bigint::BigInt;
79

8-
/*
9-
#[derive(Debug)]
10-
11-
#[derive(Debug)]
12-
pub struct Node {
13-
pub location: Location,
14-
}
15-
*/
16-
1710
#[allow(clippy::large_enum_variant)]
1811
#[derive(Debug, PartialEq)]
1912
pub enum Top {
@@ -23,6 +16,7 @@ pub enum Top {
2316
}
2417

2518
#[derive(Debug, PartialEq)]
19+
/// A full python program, it's a sequence of statements.
2620
pub struct Program {
2721
pub statements: Suite,
2822
}
@@ -45,89 +39,126 @@ pub type Suite = Vec<Statement>;
4539
/// Abstract syntax tree nodes for python statements.
4640
#[derive(Debug, PartialEq)]
4741
pub enum StatementType {
42+
/// A [`break`](https://docs.python.org/3/reference/simple_stmts.html#the-break-statement) statement.
4843
Break,
44+
45+
/// A [`continue`](https://docs.python.org/3/reference/simple_stmts.html#the-continue-statement) statement.
4946
Continue,
50-
Return {
51-
value: Option<Expression>,
52-
},
53-
Import {
54-
names: Vec<ImportSymbol>,
55-
},
47+
48+
/// A [`return`](https://docs.python.org/3/reference/simple_stmts.html#the-return-statement) statement.
49+
/// This is used to return from a function.
50+
Return { value: Option<Expression> },
51+
52+
/// An [`import`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement) statement.
53+
Import { names: Vec<ImportSymbol> },
54+
55+
/// An [`import` `from`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement) statement.
5656
ImportFrom {
5757
level: usize,
5858
module: Option<String>,
5959
names: Vec<ImportSymbol>,
6060
},
61+
62+
/// A [`pass`](https://docs.python.org/3/reference/simple_stmts.html#pass) statement.
6163
Pass,
64+
65+
/// An [`assert`](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement) statement.
6266
Assert {
6367
test: Expression,
6468
msg: Option<Expression>,
6569
},
66-
Delete {
67-
targets: Vec<Expression>,
68-
},
70+
71+
/// A `del` statement, to delete some variables.
72+
Delete { targets: Vec<Expression> },
73+
74+
/// Variable assignment. Note that we can assign to multiple targets.
6975
Assign {
7076
targets: Vec<Expression>,
7177
value: Expression,
7278
},
79+
80+
/// Augmented assignment.
7381
AugAssign {
7482
target: Box<Expression>,
7583
op: Operator,
7684
value: Box<Expression>,
7785
},
86+
87+
/// A type annotated assignment.
7888
AnnAssign {
7989
target: Box<Expression>,
8090
annotation: Box<Expression>,
8191
value: Option<Expression>,
8292
},
83-
Expression {
84-
expression: Expression,
85-
},
86-
Global {
87-
names: Vec<String>,
88-
},
89-
Nonlocal {
90-
names: Vec<String>,
91-
},
93+
94+
/// An expression used as a statement.
95+
Expression { expression: Expression },
96+
97+
/// The [`global`](https://docs.python.org/3/reference/simple_stmts.html#the-global-statement) statement,
98+
/// to declare names as global variables.
99+
Global { names: Vec<String> },
100+
101+
/// A [`nonlocal`](https://docs.python.org/3/reference/simple_stmts.html#the-nonlocal-statement) statement,
102+
/// to declare names a non-local variables.
103+
Nonlocal { names: Vec<String> },
104+
105+
/// An [`if`](https://docs.python.org/3/reference/compound_stmts.html#the-if-statement) statement.
92106
If {
93107
test: Expression,
94108
body: Suite,
95109
orelse: Option<Suite>,
96110
},
111+
112+
/// A [`while`](https://docs.python.org/3/reference/compound_stmts.html#the-while-statement) statement.
97113
While {
98114
test: Expression,
99115
body: Suite,
100116
orelse: Option<Suite>,
101117
},
118+
119+
/// The [`with`](https://docs.python.org/3/reference/compound_stmts.html#the-with-statement) statement.
102120
With {
103121
is_async: bool,
104122
items: Vec<WithItem>,
105123
body: Suite,
106124
},
125+
126+
/// A [`for`](https://docs.python.org/3/reference/compound_stmts.html#the-for-statement) statement.
127+
/// Contains the body of the loop, and the `else` clause.
107128
For {
108129
is_async: bool,
109130
target: Box<Expression>,
110131
iter: Box<Expression>,
111132
body: Suite,
112133
orelse: Option<Suite>,
113134
},
135+
136+
/// A `raise` statement.
114137
Raise {
115138
exception: Option<Expression>,
116139
cause: Option<Expression>,
117140
},
141+
142+
/// A [`try`](https://docs.python.org/3/reference/compound_stmts.html#the-try-statement) statement.
118143
Try {
119144
body: Suite,
120145
handlers: Vec<ExceptHandler>,
121146
orelse: Option<Suite>,
122147
finalbody: Option<Suite>,
123148
},
149+
150+
/// A [class definition](https://docs.python.org/3/reference/compound_stmts.html#class-definitions).
124151
ClassDef {
125152
name: String,
126153
body: Suite,
127154
bases: Vec<Expression>,
128155
keywords: Vec<Keyword>,
129156
decorator_list: Vec<Expression>,
130157
},
158+
159+
/// A [function definition](https://docs.python.org/3/reference/compound_stmts.html#function-definitions).
160+
/// Contains the name of the function, it's body
161+
/// some decorators and formal parameters to the function.
131162
FunctionDef {
132163
is_async: bool,
133164
name: String,
@@ -144,95 +175,150 @@ pub struct WithItem {
144175
pub optional_vars: Option<Expression>,
145176
}
146177

178+
/// An expression at a given location in the sourcecode.
147179
pub type Expression = Located<ExpressionType>;
148180

181+
/// A certain type of expression.
149182
#[derive(Debug, PartialEq)]
150183
pub enum ExpressionType {
151184
BoolOp {
152185
op: BooleanOperator,
153186
values: Vec<Expression>,
154187
},
188+
189+
/// A binary operation on two operands.
155190
Binop {
156191
a: Box<Expression>,
157192
op: Operator,
158193
b: Box<Expression>,
159194
},
195+
196+
/// Subscript operation.
160197
Subscript {
161198
a: Box<Expression>,
162199
b: Box<Expression>,
163200
},
201+
202+
/// An unary operation.
164203
Unop {
165204
op: UnaryOperator,
166205
a: Box<Expression>,
167206
},
207+
208+
/// An await expression.
168209
Await {
169210
value: Box<Expression>,
170211
},
212+
213+
/// A yield expression.
171214
Yield {
172215
value: Option<Box<Expression>>,
173216
},
217+
218+
// A yield from expression.
174219
YieldFrom {
175220
value: Box<Expression>,
176221
},
222+
223+
/// A chained comparison. Note that in python you can use
224+
/// `1 < a < 10` for example.
177225
Compare {
178226
vals: Vec<Expression>,
179227
ops: Vec<Comparison>,
180228
},
229+
230+
/// Attribute access in the form of `value.name`.
181231
Attribute {
182232
value: Box<Expression>,
183233
name: String,
184234
},
235+
236+
/// A call expression.
185237
Call {
186238
function: Box<Expression>,
187239
args: Vec<Expression>,
188240
keywords: Vec<Keyword>,
189241
},
242+
243+
/// A numeric literal.
190244
Number {
191245
value: Number,
192246
},
247+
248+
/// A `list` literal value.
193249
List {
194250
elements: Vec<Expression>,
195251
},
252+
253+
/// A `tuple` literal value.
196254
Tuple {
197255
elements: Vec<Expression>,
198256
},
257+
258+
/// A `dict` literal value.
259+
/// For example: `{2: 'two', 3: 'three'}`
199260
Dict {
200261
elements: Vec<(Option<Expression>, Expression)>,
201262
},
263+
264+
/// A `set` literal.
202265
Set {
203266
elements: Vec<Expression>,
204267
},
268+
205269
Comprehension {
206270
kind: Box<ComprehensionKind>,
207271
generators: Vec<Comprehension>,
208272
},
273+
274+
/// A starred expression.
209275
Starred {
210276
value: Box<Expression>,
211277
},
278+
279+
/// A slice expression.
212280
Slice {
213281
elements: Vec<Expression>,
214282
},
283+
284+
/// A string literal.
215285
String {
216286
value: StringGroup,
217287
},
288+
289+
/// A bytes literal.
218290
Bytes {
219291
value: Vec<u8>,
220292
},
293+
294+
/// An identifier, designating a certain variable or type.
221295
Identifier {
222296
name: String,
223297
},
298+
299+
/// A `lambda` function expression.
224300
Lambda {
225301
args: Box<Parameters>,
226302
body: Box<Expression>,
227303
},
304+
305+
/// An if-expression.
228306
IfExpression {
229307
test: Box<Expression>,
230308
body: Box<Expression>,
231309
orelse: Box<Expression>,
232310
},
311+
312+
/// The literal 'True'.
233313
True,
314+
315+
/// The literal 'False'.
234316
False,
317+
318+
// The literal `None`.
235319
None,
320+
321+
/// The ellipsis literal `...`.
236322
Ellipsis,
237323
}
238324

@@ -282,10 +368,10 @@ impl Expression {
282368
}
283369
}
284370

285-
/*
286-
* In cpython this is called arguments, but we choose parameters to
287-
* distinguish between function parameters and actual call arguments.
288-
*/
371+
/// Formal parameters to a function.
372+
///
373+
/// In cpython this is called arguments, but we choose parameters to
374+
/// distinguish between function parameters and actual call arguments.
289375
#[derive(Debug, PartialEq, Default)]
290376
pub struct Parameters {
291377
pub args: Vec<Parameter>,
@@ -296,6 +382,7 @@ pub struct Parameters {
296382
pub kw_defaults: Vec<Option<Expression>>,
297383
}
298384

385+
/// A single formal parameter to a function.
299386
#[derive(Debug, PartialEq, Default)]
300387
pub struct Parameter {
301388
pub location: Location,
@@ -312,6 +399,7 @@ pub enum ComprehensionKind {
312399
Dict { key: Expression, value: Expression },
313400
}
314401

402+
/// A list/set/dict/generator compression.
315403
#[derive(Debug, PartialEq)]
316404
pub struct Comprehension {
317405
pub location: Location,
@@ -341,6 +429,7 @@ pub struct ExceptHandler {
341429
pub body: Suite,
342430
}
343431

432+
/// An operator for a binary operation (an operation with two operands).
344433
#[derive(Debug, PartialEq)]
345434
pub enum Operator {
346435
Add,
@@ -358,12 +447,14 @@ pub enum Operator {
358447
FloorDiv,
359448
}
360449

450+
/// A boolean operation.
361451
#[derive(Debug, PartialEq)]
362452
pub enum BooleanOperator {
363453
And,
364454
Or,
365455
}
366456

457+
/// An unary operator. This is an operation with only a single operand.
367458
#[derive(Debug, PartialEq)]
368459
pub enum UnaryOperator {
369460
Pos,
@@ -372,6 +463,7 @@ pub enum UnaryOperator {
372463
Inv,
373464
}
374465

466+
/// A comparison operation.
375467
#[derive(Debug, PartialEq)]
376468
pub enum Comparison {
377469
Equal,
@@ -386,6 +478,7 @@ pub enum Comparison {
386478
IsNot,
387479
}
388480

481+
/// A numeric literal.
389482
#[derive(Debug, PartialEq)]
390483
pub enum Number {
391484
Integer { value: BigInt },

0 commit comments

Comments
 (0)