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

["Burakov, Anatoly" <anatoly.burakov@intel.com>]

On 03-May-21 10:02 PM, Thomas Monjalon wrote:
> 21/04/2021 11:11, Conor Walsh:
>> +  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.
> 
> [...]
>> +* ``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.

-- 
Thanks,
Anatoly