From 37ef2c34e437b04fb9b7e3126ea3bdd203a35e85 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 3 Oct 2021 12:50:06 -0600 Subject: [PATCH] docs: dt: Fix a few grammar nits in the binding/schema docs Add missing hyphens and reword one sentence for clarity. Signed-off-by: Simon Glass Reviewed-by: Randy Dunlap Link: https://lore.kernel.org/r/20211003124936.1.Idc7beddc77250bca0cfb5912b56be719d9073bc4@changeid Signed-off-by: Rob Herring --- .../devicetree/bindings/example-schema.yaml | 14 ++++----- .../devicetree/bindings/writing-bindings.rst | 2 +- .../devicetree/bindings/writing-schema.rst | 29 ++++++++++--------- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml index ff6ec65145cf..c078796ae1b5 100644 --- a/Documentation/devicetree/bindings/example-schema.yaml +++ b/Documentation/devicetree/bindings/example-schema.yaml @@ -119,7 +119,7 @@ properties: # valid for this binding. clock-frequency: - # The type is set in the core schema. Per device schema only need to set + # The type is set in the core schema. Per-device schema only need to set # constraints on the possible values. minimum: 100 maximum: 400000 @@ -133,24 +133,24 @@ properties: # *-supply is always a single phandle, so nothing more to define. foo-supply: true - # Vendor specific properties + # Vendor-specific properties # - # Vendor specific properties have slightly different schema requirements than + # Vendor-specific properties have slightly different schema requirements than # common properties. They must have at least a type definition and # 'description'. vendor,int-property: - description: Vendor specific properties must have a description + description: Vendor-specific properties must have a description $ref: /schemas/types.yaml#/definitions/uint32 enum: [2, 4, 6, 8, 10] vendor,bool-property: - description: Vendor specific properties must have a description. Boolean + description: Vendor-specific properties must have a description. Boolean properties are one case where the json-schema 'type' keyword can be used directly. type: boolean vendor,string-array-property: - description: Vendor specific properties should reference a type in the + description: Vendor-specific properties should reference a type in the core schema. $ref: /schemas/types.yaml#/definitions/string-array items: @@ -158,7 +158,7 @@ properties: - enum: [baz, boo] vendor,property-in-standard-units-microvolt: - description: Vendor specific properties having a standard unit suffix + description: Vendor-specific properties having a standard unit suffix don't need a type. enum: [ 100, 200, 300 ] diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst index f7dfb98c156e..18d9e0689d49 100644 --- a/Documentation/devicetree/bindings/writing-bindings.rst +++ b/Documentation/devicetree/bindings/writing-bindings.rst @@ -44,7 +44,7 @@ Properties of prior implementations. DO add new compatibles in case there are new features or bugs. -- DO use a vendor prefix on device specific property names. Consider if +- DO use a vendor prefix on device-specific property names. Consider if properties could be common among devices of the same class. Check other existing bindings for similar devices. diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 23d6579aea2c..ea21c72aeb37 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -4,7 +4,7 @@ Writing Devicetree Bindings in json-schema ========================================== Devicetree bindings are written using json-schema vocabulary. Schema files are -written in a JSON compatible subset of YAML. YAML is used instead of JSON as it +written in a JSON-compatible subset of YAML. YAML is used instead of JSON as it is considered more human readable and has some advantages such as allowing comments (Prefixed with '#'). @@ -22,16 +22,16 @@ $id URI typically containing the binding's filename and path. For DT schema, it must begin with "http://devicetree.org/schemas/". The URL is used in constructing references to other files specified in schema "$ref" properties. A $ref value - with a leading '/' will have the hostname prepended. A $ref value a relative - path or filename only will be prepended with the hostname and path components - of the current schema file's '$id' value. A URL is used even for local files, - but there may not actually be files present at those locations. + with a leading '/' will have the hostname prepended. A $ref value with only a + relative path or filename will be prepended with the hostname and path + components of the current schema file's '$id' value. A URL is used even for + local files, but there may not actually be files present at those locations. $schema Indicates the meta-schema the schema file adheres to. title - A one line description on the contents of the binding schema. + A one-line description on the contents of the binding schema. maintainers A DT specific property. Contains a list of email address(es) @@ -45,8 +45,8 @@ description select Optional. A json-schema used to match nodes for applying the - schema. By default without 'select', nodes are matched against their possible - compatible string values or node name. Most bindings should not need select. + schema. By default, without 'select', nodes are matched against their possible + compatible-string values or node name. Most bindings should not need select. allOf Optional. A list of other schemas to include. This is used to @@ -56,7 +56,8 @@ allOf properties A set of sub-schema defining all the DT properties for the binding. The exact schema syntax depends on whether properties are known, - common properties (e.g. 'interrupts') or are binding/vendor specific properties. + common properties (e.g. 'interrupts') or are binding/vendor-specific + properties. A property can also define a child DT node with child properties defined under it. @@ -81,23 +82,23 @@ Property Schema The 'properties' section of the schema contains all the DT properties for a binding. Each property contains a set of constraints using json-schema -vocabulary for that property. The properties schemas are what is used for +vocabulary for that property. The properties schemas are what are used for validation of DT files. -For common properties, only additional constraints not covered by the common +For common properties, only additional constraints not covered by the common, binding schema need to be defined such as how many values are valid or what possible values are valid. -Vendor specific properties will typically need more detailed schema. With the +Vendor-specific properties will typically need more detailed schema. With the exception of boolean properties, they should have a reference to a type in schemas/types.yaml. A "description" property is always required. -The Devicetree schemas don't exactly match the YAML encoded DT data produced by +The Devicetree schemas don't exactly match the YAML-encoded DT data produced by dtc. They are simplified to make them more compact and avoid a bunch of boilerplate. The tools process the schema files to produce the final schema for validation. There are currently 2 transformations the tools perform. -The default for arrays in json-schema is they are variable sized and allow more +The default for arrays in json-schema is they are variable-sized and allow more entries than explicitly defined. This can be restricted by defining 'minItems', 'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed size is desired in most cases, so these properties are added based on the