Fix docstring lints as reported by internal linter. (#180)
diff --git a/compiler/front_end/attribute_checker.py b/compiler/front_end/attribute_checker.py index 9e7fec2..d1df30c 100644 --- a/compiler/front_end/attribute_checker.py +++ b/compiler/front_end/attribute_checker.py
@@ -44,6 +44,7 @@ def _valid_back_ends(attr, module_source_file): + """Checks that `attr` holds a valid list of back end specifiers.""" if not re.match( r"^(?:\s*[a-z][a-z0-9_]*\s*(?:,\s*[a-z][a-z0-9_]*\s*)*,?)?\s*$", attr.value.string_constant.text,
diff --git a/compiler/front_end/constraints.py b/compiler/front_end/constraints.py index 3249e6d..852c9ad 100644 --- a/compiler/front_end/constraints.py +++ b/compiler/front_end/constraints.py
@@ -436,6 +436,7 @@ def _check_allowed_in_bits(type_ir, type_definition, source_file_name, ir, errors): + """Verifies that atomic fields have types that are allowed in `bits`.""" if not type_ir.HasField("atomic_type"): return referenced_type_definition = ir_util.find_object(type_ir.atomic_type.reference, ir)
diff --git a/compiler/front_end/dependency_checker.py b/compiler/front_end/dependency_checker.py index 8a9e903..fb622e1 100644 --- a/compiler/front_end/dependency_checker.py +++ b/compiler/front_end/dependency_checker.py
@@ -23,14 +23,15 @@ def _add_reference_to_dependencies( reference, dependencies, name, source_file_name, errors ): + """Adds the specified `reference` to the `dependencies` set.""" if reference.canonical_name.object_path[0] in { "$is_statically_sized", "$static_size_in_bits", "$next", }: - # This error is a bit opaque, but given that the compiler used to crash on - # this case -- for a couple of years -- and no one complained, it seems - # safe to assume that this is a rare error. + # This error is a bit opaque, but given that the compiler used to crash + # on this case -- for a couple of years -- and no one complained, it + # seems safe to assume that this is a rare error. errors.append( [ error.error(
diff --git a/compiler/front_end/format_emb.py b/compiler/front_end/format_emb.py index df9bcf3..fc7bf94 100644 --- a/compiler/front_end/format_emb.py +++ b/compiler/front_end/format_emb.py
@@ -485,6 +485,7 @@ " type-definition* struct-field-block Dedent" ) def _structure_body(indent, docs, attributes, type_definitions, fields, dedent, config): + """Formats a structure (`bits` or `struct`) body.""" del indent, dedent # Unused. spacing = [_Row("field-separator")] if _should_add_blank_lines(fields) else [] columnized_fields = _columnize(fields, config.indent_width, indent_columns=2) @@ -609,6 +610,7 @@ ' field-location "bits" ":" Comment? eol anonymous-bits-body' ) def _inline_bits(location, bits, colon, comment, eol, body): + """Formats an inline `bits` definition.""" # Even though an anonymous bits field technically defines a new, anonymous # type, conceptually it's more like defining a bunch of fields on the # surrounding type, so it is treated as an inline list of blocks, instead of @@ -1017,6 +1019,7 @@ @_formats("or-expression-right -> or-operator comparison-expression") @_formats("and-expression-right -> and-operator comparison-expression") def _concatenate_with_prefix_spaces(*elements): + """Concatenates non-empty `elements` with leading spaces.""" return "".join(" " + element for element in elements if element) @@ -1032,10 +1035,12 @@ ) @_formats('parameter-definition-list-tail -> "," parameter-definition') def _concatenate_with_spaces(*elements): + """Concatenates non-empty `elements` with spaces between.""" return _concatenate_with(" ", *elements) def _concatenate_with(joiner, *elements): + """Concatenates non-empty `elements` with `joiner` between.""" return joiner.join(element for element in elements if element)
diff --git a/compiler/front_end/lr1.py b/compiler/front_end/lr1.py index be99f95..579d729 100644 --- a/compiler/front_end/lr1.py +++ b/compiler/front_end/lr1.py
@@ -36,16 +36,17 @@ ): """An Item is an LR(1) Item: a production, a cursor location, and a terminal. - An Item represents a partially-parsed production, and a lookahead symbol. The - position of the dot indicates what portion of the production has been parsed. - Generally, Items are an internal implementation detail, but they can be useful - elsewhere, particularly for debugging. + An Item represents a partially-parsed production, and a lookahead symbol. + The position of the dot indicates what portion of the production has been + parsed. Generally, Items are an internal implementation detail, but they + can be useful elsewhere, particularly for debugging. Attributes: - production: The Production this Item covers. - dot: The index of the "dot" in production's rhs. - terminal: The terminal lookahead symbol that follows the production in the - input stream. + production: The Production this Item covers. + dot: The index of the "dot" in production's rhs. + terminal: The terminal lookahead symbol that follows the production in + the input stream. + next_symbol: The lookahead symbol. """ def __str__(self):
diff --git a/compiler/front_end/module_ir.py b/compiler/front_end/module_ir.py index bd27c8a..4a459c2 100644 --- a/compiler/front_end/module_ir.py +++ b/compiler/front_end/module_ir.py
@@ -339,6 +339,7 @@ attribute_value, close_bracket, ): + """Assembles an attribute IR node.""" del open_bracket, colon, close_bracket # Unused. if context_specifier.list: return ir_data.Attribute( @@ -460,14 +461,15 @@ ' ":" logical-expression' ) def _choice_expression(condition, question, if_true, colon, if_false): + """Constructs an IR node for a choice operator (`?:`) expression.""" location = parser_types.make_location( condition.source_location.start, if_false.source_location.end ) operator_location = parser_types.make_location( question.source_location.start, colon.source_location.end ) - # The function_name is a bit weird, but should suffice for any error messages - # that might need it. + # The function_name is a bit weird, but should suffice for any error + # messages that might need it. return ir_data.Expression( function=ir_data.Function( function=ir_data.FunctionMapping.CHOICE, @@ -1284,6 +1286,7 @@ def _enum_value( name, equals, expression, attribute, documentation, comment, newline, body ): + """Constructs an IR node for an enum value statement (`NAME = value`).""" del equals, comment, newline # Unused. result = ir_data.EnumValue( name=name,
diff --git a/compiler/front_end/synthetics.py b/compiler/front_end/synthetics.py index 1b331a3..f55e32f 100644 --- a/compiler/front_end/synthetics.py +++ b/compiler/front_end/synthetics.py
@@ -236,6 +236,7 @@ def _maybe_replace_next_keyword_in_expression( expression_ir, last_location, source_file_name, errors ): + """Replaces the `$next` keyword in an expression.""" if not expression_ir.HasField("builtin_reference"): return if (
diff --git a/compiler/front_end/type_check.py b/compiler/front_end/type_check.py index f562cc8..c3f7870 100644 --- a/compiler/front_end/type_check.py +++ b/compiler/front_end/type_check.py
@@ -133,6 +133,7 @@ def _type_check_operation(expression, source_file_name, ir, errors): + """Type checks a function or operator expression.""" for arg in expression.function.args: _type_check_expression(arg, source_file_name, ir, errors) function = expression.function.function