diff mbox series

[04/10] docs: write an elided passage as a comment

Message ID 20260922020339.481929-5-twoerner@gmail.com
State Under Review
Headers show
Series docs: editorial repairs to the examples | expand

Commit Message

Trevor Woerner Sept. 22, 2026, 2:03 a.m. UTC
Several examples stand in for code they leave out with a bare "..." or a
column of dots on a line of their own. Neither is valid in the language
around it, so the example cannot say what language it is without also
saying something false about itself.

Use a comment instead, in whatever language the example is written in,
and say in it what was left out. The ellipsis on its own raises a
question - what is missing here, and does it matter? - that a few words
can answer at no cost to the reader.

AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 documentation/bsp-manual/bsp.rst                 |  4 +---
 documentation/kernel-dev/common.rst              | 14 +++++++-------
 documentation/migration-guides/migration-3.2.rst |  2 +-
 documentation/overview-manual/concepts.rst       |  2 +-
 4 files changed, 10 insertions(+), 12 deletions(-)
diff mbox series

Patch

diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst
index dd613326942a..93af13f789d1 100644
--- a/documentation/bsp-manual/bsp.rst
+++ b/documentation/bsp-manual/bsp.rst
@@ -561,9 +561,7 @@  statements from the Raspberry Pi ``conf/layer.conf`` file::
 
    # Additional license directories.
    LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
-   .
-   .
-   .
+   # ... and so on for the rest of the file ...
 
 This file simply makes :term:`BitBake` aware of the recipes and configuration
 directories. The file must exist so that the OpenEmbedded build system can
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 17b7dbac928f..555aadc76a6c 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -681,9 +681,9 @@  the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
              printk("*************************************\n");
 
              if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
-                   .
-                   .
-                   .
+                   /*
+                    * ... remaining code unchanged ...
+                    */
 
 #. *Build the Updated Kernel Source:* To build the updated kernel
    source, use ``devtool``::
@@ -817,9 +817,9 @@  Section.
              printk("*************************************\n");
 
              if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
-                   .
-                   .
-                   .
+                   /*
+                    * ... remaining code unchanged ...
+                    */
 
 #. *Stage and Commit Your Changes:* Use standard Git commands to stage
    and commit the changes you just made::
@@ -1598,7 +1598,7 @@  looks much like the one provided with the ``hello-mod`` template::
 
    modules_install:
         $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
-   ...
+   # ... remaining rules ...
 
 The important point to note here is the :term:`KERNEL_SRC` variable. The
 :ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH`
diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst
index 5cb958e75047..a037e6f51c53 100644
--- a/documentation/migration-guides/migration-3.2.rst
+++ b/documentation/migration-guides/migration-3.2.rst
@@ -100,7 +100,7 @@  This also applies when conditionally adding packages to :term:`PACKAGES` where
 those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
 
     PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
-    ...
+    # ... elsewhere in the same recipe ...
     RDEPENDS_${PN}-pulseaudio-conf += "\
             ${MLPREFIX}libasound-module-conf-pulse \
             ${MLPREFIX}libasound-module-ctl-pulse \
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index 3bf672c78387..1e9c6d3a6f0b 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -2193,7 +2193,7 @@  accomplished using fakeroot.
    ``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
 
       fakeroot do_mytask () {
-          ...
+          # ... steps to perform task here ...
       }
       do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"