DPDK patches and discussions
 help / color / mirror / Atom feed
From: Nandini Persad <nandinipersad361@gmail.com>
To: dev@dpdk.org
Subject: [PATCH v2 7/9] doc: reword cmdline section in prog guide
Date: Thu, 20 Jun 2024 19:32:52 -0700	[thread overview]
Message-ID: <20240621023254.4258-7-nandinipersad361@gmail.com> (raw)
In-Reply-To: <20240621023254.4258-1-nandinipersad361@gmail.com>

Minor syntax edits made to the cmdline section.

Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
---
 doc/guides/prog_guide/cmdline.rst | 34 +++++++++++++++----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/doc/guides/prog_guide/cmdline.rst b/doc/guides/prog_guide/cmdline.rst
index 6b10ab6c99..8aa1ef180b 100644
--- a/doc/guides/prog_guide/cmdline.rst
+++ b/doc/guides/prog_guide/cmdline.rst
@@ -62,7 +62,7 @@ The format of the list file must follow these requirements:
 
 * One command per line
 
-* Variable fields are prefixed by the type-name in angle-brackets, for example:
+* Variable fields are prefixed by the type-name in angle-brackets. For example:
 
   * ``<STRING>message``
 
@@ -75,7 +75,7 @@ The format of the list file must follow these requirements:
   * ``<IPv6>dst_ip6``
 
 * Variable fields, which take their values from a list of options,
-  have the comma-separated option list placed in braces, rather than by the type name.
+  have the comma-separated option list placed in braces rather than by the type name.
   For example,
 
   * ``<(rx,tx,rxtx)>mode``
@@ -112,7 +112,7 @@ The generated content includes:
 
 * A command-line context array definition, suitable for passing to ``cmdline_new``
 
-If so desired, the script can also output function stubs for the callback functions for each command.
+If needed, the script can also output function stubs for the callback functions for each command.
 This behaviour is triggered by passing the ``--stubs`` flag to the script.
 In this case, an output file must be provided with a filename ending in ".h",
 and the callback stubs will be written to an equivalent ".c" file.
@@ -120,7 +120,7 @@ and the callback stubs will be written to an equivalent ".c" file.
 .. note::
 
    The stubs are written to a separate file,
-   to allow continuous use of the script to regenerate the command-line header,
+   to allow continuous use of the script to regenerate the command-line header
    without overwriting any code the user has added to the callback functions.
    This makes it easy to incrementally add new commands to an existing application.
 
@@ -154,7 +154,7 @@ the callback functions would be:
 These functions must be provided by the developer. However, as stated above,
 stub functions may be generated by the script automatically using the ``--stubs`` parameter.
 
-The same "cmdname" stem is used in the naming of the generated structures too.
+The same "cmdname" stem is used in the naming of the generated structures as well.
 To get to the results structure for each command above,
 the ``parsed_result`` parameter should be cast to ``struct cmd_quit_result``
 or ``struct cmd_show_port_stats_result`` respectively.
@@ -176,13 +176,12 @@ Integrating with the Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To integrate the script output with the application,
-we must ``#include`` the generated header into our applications C file,
+we must ``#include`` the generated header into our application's C file,
 and then have the command-line created via either ``cmdline_new`` or ``cmdline_stdin_new``.
 The first parameter to the function call should be the context array in the generated header file,
 ``ctx`` by default (Modifiable via script parameter).
 
-The callback functions may be in this same file, or in a separate one -
-they just need to be available to the linker at build-time.
+The callback functions may be in the same or separate file, as long as they are available to the linker at build-time.
 
 Limitations of the Script Approach
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -242,19 +241,19 @@ The resulting struct looks like:
 
 As before, we choose names to match the tokens in the command.
 Since our numeric parameter is a 16-bit value, we use ``uint16_t`` type for it.
-Any of the standard sized integer types can be used as parameters, depending on the desired result.
+Any of the standard-sized integer types can be used as parameters depending on the desired result.
 
 Beyond the standard integer types,
-the library also allows variable parameters to be of a number of other types,
+the library also allows variable parameters to be of a number of other types
 as called out in the feature list above.
 
 * For variable string parameters,
   the type should be ``cmdline_fixed_string_t`` - the same as for fixed tokens,
   but these will be initialized differently (as described below).
 
-* For ethernet addresses use type ``struct rte_ether_addr``
+* For ethernet addresses, use type ``struct rte_ether_addr``
 
-* For IP addresses use type ``cmdline_ipaddr_t``
+* For IP addresses, use type ``cmdline_ipaddr_t``
 
 Providing Field Initializers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -267,6 +266,7 @@ For fixed string tokens, like "quit", "show" and "port", the initializer will be
    static cmdline_parse_token_string_t cmd_quit_quit_tok =
       TOKEN_STRING_INITIALIZER(struct cmd_quit_result, quit, "quit");
 
+
 The convention for naming used here is to include the base name of the overall result structure -
 ``cmd_quit`` in this case,
 as well as the name of the field within that structure - ``quit`` in this case, followed by ``_tok``.
@@ -311,8 +311,8 @@ The callback function should have type:
 where the first parameter is a pointer to the result structure defined above,
 the second parameter is the command-line instance,
 and the final parameter is a user-defined pointer provided when we associate the callback with the command.
-Most callback functions only use the first parameter, or none at all,
-but the additional two parameters provide some extra flexibility,
+Most callback functions only use the first parameter or none at all,
+but the additional two parameters provide some extra flexibility
 to allow the callback to work with non-global state in your application.
 
 For our two example commands, the relevant callback functions would look very similar in definition.
@@ -341,7 +341,7 @@ Associating Callback and Command
 
 The ``cmdline_parse_inst_t`` type defines a "parse instance",
 i.e. a sequence of tokens to be matched and then an associated function to be called.
-Also included in the instance type are a field for help text for the command,
+Also included in the instance type are a field for help text for the command
 and any additional user-defined parameter to be passed to the callback functions referenced above.
 For example, for our simple "quit" command:
 
@@ -362,8 +362,8 @@ then set the user-defined parameter to NULL,
 provide a help message to be given, on request, to the user explaining the command,
 before finally listing out the single token to be matched for this command instance.
 
-For our second, port stats, example,
-as well as making things a little more complicated by having multiple tokens to be matched,
+For our second "port stats" example,
+as well as making things more complex by having multiple tokens to be matched,
 we can also demonstrate passing in a parameter to the function.
 Let us suppose that our application does not always use all the ports available to it,
 but instead only uses a subset of the ports, stored in an array called ``active_ports``.
-- 
2.34.1


  parent reply	other threads:[~2024-06-21  2:33 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-05-13 15:59 [PATCH 0/9] reowrd " Nandini Persad
2024-05-13 15:59 ` [PATCH 1/9] doc: reword design section in contributors guidelines Nandini Persad
2024-05-13 15:59 ` [PATCH 2/9] doc: reword pmd section in prog guide Nandini Persad
2024-05-13 15:59 ` [PATCH 3/9] doc: reword argparse " Nandini Persad
2024-05-13 19:01   ` Stephen Hemminger
2024-05-13 15:59 ` [PATCH 4/9] doc: reword service cores " Nandini Persad
2024-05-13 15:59 ` [PATCH 5/9] doc: reword trace library " Nandini Persad
2024-05-13 15:59 ` [PATCH 6/9] doc: reword log " Nandini Persad
2024-05-13 15:59 ` [PATCH 7/9] doc: reword cmdline " Nandini Persad
2024-05-13 15:59 ` [PATCH 8/9] doc: reword stack library " Nandini Persad
2024-05-13 15:59 ` [PATCH 9/9] doc: reword rcu " Nandini Persad
2024-06-21  2:32 ` [PATCH v2 1/9] doc: reword pmd " Nandini Persad
2024-06-21  2:32   ` [PATCH v2 2/9] doc: reword argparse " Nandini Persad
2024-06-22 14:53     ` Stephen Hemminger
2024-06-21  2:32   ` [PATCH v2 3/9] doc: reword design section in contributors guidelines Nandini Persad
2024-06-22 14:47     ` [PATCH] doc/design: minor cleanus Stephen Hemminger
2024-06-24 15:07       ` Thomas Monjalon
2024-06-21  2:32   ` [PATCH v2 4/9] doc: reword service cores section in prog guide Nandini Persad
2024-06-22 14:53     ` Stephen Hemminger
2024-06-21  2:32   ` [PATCH v2 5/9] doc: reword trace library " Nandini Persad
2024-06-22 14:54     ` Stephen Hemminger
2024-06-21  2:32   ` [PATCH v2 6/9] doc: reword log " Nandini Persad
2024-06-22 14:55     ` Stephen Hemminger
2024-06-21  2:32   ` Nandini Persad [this message]
2024-06-22 14:55     ` [PATCH v2 7/9] doc: reword cmdline " Stephen Hemminger
2024-06-21  2:32   ` [PATCH v2 8/9] doc: reword stack library " Nandini Persad
2024-06-22 14:55     ` Stephen Hemminger
2024-06-21  2:32   ` [PATCH v2 9/9] doc: reword rcu " Nandini Persad
2024-06-22 14:55     ` Stephen Hemminger
2024-06-22 14:52   ` [PATCH v2 1/9] doc: reword pmd " Stephen Hemminger

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=20240621023254.4258-7-nandinipersad361@gmail.com \
    --to=nandinipersad361@gmail.com \
    --cc=dev@dpdk.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).