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

[Thomas Monjalon <thomas@monjalon.net>]

04/05/2021 12:35, Ferruh Yigit:
> On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
> > 04/05/2021 11:32, Burakov, Anatoly:
> >> 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.
> > 
> > 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.