From f9ed1c9c30445fa221eedc38382ee132fbb2171e Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Mon, 29 Jan 2024 09:28:32 -0800 Subject: [PATCH 1/2] doc: fix misformatted list in nbapi docs Signed-off-by: Quentin Young --- .../retrofitting-configuration-commands.rst | 31 ++++++++++--------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/developer/northbound/retrofitting-configuration-commands.rst b/doc/developer/northbound/retrofitting-configuration-commands.rst index 47726108568f..58d7910f17e6 100644 --- a/doc/developer/northbound/retrofitting-configuration-commands.rst +++ b/doc/developer/northbound/retrofitting-configuration-commands.rst @@ -989,27 +989,28 @@ CLI commands should be rewritten but maintained in the same file. Since all CLI configuration commands from FRR will need to be rewritten, this is an excellent opportunity to rework this part of the code to make the commands easier to maintain and extend. These are the three main -recommendations: 1. Always use DEFPY instead of DEFUN to improve code -readability. 2. Always try to join multiple DEFUNs into a single DEFPY -whenever possible. As an example, there’s no need to have both -``distance (1-255) A.B.C.D/M`` and ``distance (1-255) A.B.C.D/M WORD`` -when a single ``distance (1-255) A.B.C.D/M [WORD]`` would suffice. 3. -When necessary, create a separate DEFPY for ``no`` commands so that part -of the configuration command can be made optional for convenience. -Example: -``no timers basic [(5-2147483647) (5-2147483647) (5-2147483647)]``. In -this example, everything after ``no timers basic`` is ignored by FRR, so -it makes sense to accept ``no timers basic`` as a valid command. But it -also makes sense to accept all parameters -(``no timers basic (5-2147483647) (5-2147483647) (5-2147483647)``) to -make it easier to remove the command just by prefixing a “no” to it. +recommendations: + +#. Always use DEFPY instead of DEFUN to improve code readability +#. Always try to join multiple DEFUNs into a single DEFPY whenever possible. As + an example, there’s no need to have both ``distance (1-255) A.B.C.D/M`` and + ``distance (1-255) A.B.C.D/M WORD`` when a single ``distance (1-255) + A.B.C.D/M [WORD]`` would suffice. +#. When necessary, create a separate DEFPY for ``no`` commands so that part of + the configuration command can be made optional for convenience. Example: + ``no timers basic [(5-2147483647) (5-2147483647) (5-2147483647)]``. In this + example, everything after ``no timers basic`` is ignored by FRR, so it makes + sense to accept ``no timers basic`` as a valid command. But it also makes + sense to accept all parameters (``no timers basic (5-2147483647) + (5-2147483647) (5-2147483647)``) to make it easier to remove the command + just by prefixing a “no” to it. To rewrite a CLI command as a dumb wrapper around the northbound callbacks, use the ``nb_cli_cfg_change()`` function. This function accepts as a parameter an array of ``cli_config_change`` structures that specify the changes that need to performed on the candidate configuration. Here’s the declaration of this structure (taken from the -*lib/northbound_cli.h* file): +``lib/northbound_cli.h`` file): .. code:: c From 5b4a3d3af9016e174b65096bc6c3d4a3817fc329 Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Mon, 29 Jan 2024 15:30:19 -0500 Subject: [PATCH 2/2] doc: update [no] recommendation Signed-off-by: Quentin Young --- .../retrofitting-configuration-commands.rst | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/doc/developer/northbound/retrofitting-configuration-commands.rst b/doc/developer/northbound/retrofitting-configuration-commands.rst index 58d7910f17e6..41408480054f 100644 --- a/doc/developer/northbound/retrofitting-configuration-commands.rst +++ b/doc/developer/northbound/retrofitting-configuration-commands.rst @@ -996,14 +996,9 @@ recommendations: an example, there’s no need to have both ``distance (1-255) A.B.C.D/M`` and ``distance (1-255) A.B.C.D/M WORD`` when a single ``distance (1-255) A.B.C.D/M [WORD]`` would suffice. -#. When necessary, create a separate DEFPY for ``no`` commands so that part of - the configuration command can be made optional for convenience. Example: - ``no timers basic [(5-2147483647) (5-2147483647) (5-2147483647)]``. In this - example, everything after ``no timers basic`` is ignored by FRR, so it makes - sense to accept ``no timers basic`` as a valid command. But it also makes - sense to accept all parameters (``no timers basic (5-2147483647) - (5-2147483647) (5-2147483647)``) to make it easier to remove the command - just by prefixing a “no” to it. +#. When making a negative form of a command, put ``[no]`` in the positive form + and use ``![...]`` to mark portions of the command that should be optional + only in the ``no`` version. To rewrite a CLI command as a dumb wrapper around the northbound callbacks, use the ``nb_cli_cfg_change()`` function. This function