Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

04/05/2021 12:35, Ferruh Yigit:

On 5/4/2021 10:59 AM, Thomas Monjalon wrote:

quoted

04/05/2021 11:32, Burakov, Anatoly:

quoted

On 03-May-21 10:02 PM, Thomas Monjalon wrote:

quoted

21/04/2021 11:11, Conor Walsh:

quoted

+  The following will include a snippet from the skeleton sample app::
+
+      .. literalinclude:: ../../../examples/skeleton/basicfwd.c
+        :language: c
+        :start-after: Display the port MAC address.
+        :end-before: Enable RX in promiscuous mode for the Ethernet device.
+        :dedent: 1

I would prefer indenting the options with 3 spaces
to make them aligned with literalinclude.

[...]

quoted

+* ``start-after`` and ``end-before`` can use any text within a given file,
+  however it may be difficult to find unique text within your code to mark the
+  start and end of your snippets. In these cases, it is recommended to include
+  explicit tags in your code to denote these locations for documentation purposes.
+
+  This can be done as follows:
+
+  .. code-block:: c
+
+    /* #guide_doc: Example feature being documented. */
+    ...
+    /* #guide_doc: End of example feature being documented. */

I think we can standardize this usage in a beautiful syntax.
My proposal, using the scissor sign:

     /* Foo bar >8 */
     foo(bar);
     /* 8< End of foo bar */

     .. literalinclude:: foobar.c
        :language: C
        :start-after: Foo bar >8
        :end-before: 8< End of foo bar

Another idea:

     /*~ Foo bar */
     foo(bar);
     /*~ End of foo bar */

     .. literalinclude:: foobar.c
        :language: C
        :start-after: ~ Foo bar
        :end-before: ~ End of foo bar

Maybe we don't need any markup for the start line and keep it natural:

     /* Foo bar */
     foo(bar);
     /* end: Foo bar */

     .. literalinclude:: foobar.c
        :language: C
        :start-after: Foo bar
        :end-before: end: Foo bar

Not having markup will 1) risk people accidentally "fixing" or otherwise 
modifying comments, and 2) has bigger potential for collisions elsewhere 
in the comments. While these aren't big risks, IMO it should be 
explicitly obvious that a comment is not just a comment but a marker docs.

Having named tags like in the original proposal is the most explicit 
version of the above, which is why i favor it, but i think it's OK to 
have a lighter-weight syntax (e.g. with scissors for example), however i 
don't think it's a good idea to leave things implicit like your last 
suggestion.

I think the first comment is not only for code extraction,
but also for code reader, that's why I think it's good to keep it natural.

+1 to Anatoly's comment, to make it obvious to the reader of the code that the
comment is used for documentation purposes and use explicit syntax for it.

So you assume the comment is only for doc extraction?
I think it can be a real comment, otherwise we'll need to have
2 lines: 1 for doc extraction, 1 for code comment.