From: Simon Glass <sjg@chromium.org>
To: devicetree@vger.kernel.org
Cc: U-Boot Mailing List <u-boot@lists.denx.de>,
Simon Glass <sjg@chromium.org>,
Arnaud Pouliquen <arnaud.pouliquen@st.com>,
Luca Ceresoli <luca@lucaceresoli.net>,
Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Rob Herring <robh+dt@kernel.org>,
Ulf Hansson <ulf.hansson@linaro.org>,
Wolfram Sang <wsa@kernel.org>,
linux-kernel@vger.kernel.org
Subject: [PATCH 1/2] docs: dt: Fix a few grammar nits in the binding/schema docs
Date: Sun, 3 Oct 2021 12:50:06 -0600 [thread overview]
Message-ID: <20211003124936.1.Idc7beddc77250bca0cfb5912b56be719d9073bc4@changeid> (raw)
Add missing hyphens and reword one sentence for clarity.
Signed-off-by: Simon Glass <sjg@chromium.org>
---
.../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 ff6ec65145cf13..c078796ae1b556 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 f7dfb98c156ee5..18d9e0689d4993 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 23d6579aea2c26..ea21c72aeb37a6 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
--
2.33.0.800.g4c38ced690-goog
next reply other threads:[~2021-10-03 18:50 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-03 18:50 Simon Glass [this message]
2021-10-03 18:58 ` [PATCH 1/2] docs: dt: Fix a few grammar nits in the binding/schema docs Randy Dunlap
2021-10-04 18:55 ` Rob Herring
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211003124936.1.Idc7beddc77250bca0cfb5912b56be719d9073bc4@changeid \
--to=sjg@chromium.org \
--cc=arnaud.pouliquen@st.com \
--cc=devicetree@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=luca@lucaceresoli.net \
--cc=mchehab+huawei@kernel.org \
--cc=robh+dt@kernel.org \
--cc=u-boot@lists.denx.de \
--cc=ulf.hansson@linaro.org \
--cc=wsa@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.