On 04-May-21 12:56 PM, Thomas Monjalon wrote:
04/05/2021 13:15, Ferruh Yigit:
On 5/4/2021 11:44 AM, Thomas Monjalon wrote:
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.
I see your point, for the cases that there is already a comment before (or
after) the code, will it be too bad to have multiple lines, something like:
/* Actual comment
* More details
*
* explicit marker */
I think explicit marker has the advantage of:
- Whoever updating the comment will know that it is a marker for the
documentation and be careful on update
- Whoever updating the code between the markers, know that it may be required to
re-visit the relevant documentation and update it because of code change
- Whoever reading the code will know that part is in a documentation, and may be
interested to go and check the relevant documentation
- Whoever reading the code, and not very familiar with DPDK convention, still
can understand what that comment is for and benefit from above
I understand these points.
But I'm afraid the proposed syntax #guide_doc:
is not so obvious for everybody.
I'm sure there can be a better syntax.
I'm not particularly attached to either syntax, as long as it's clearly
documented and explicitly visible in the code (as opposed to something
that kinda-sorta-but-doesn't-really-look-like-a-marker type syntax).
So, we'd have to give up some "natural-ness", as *that's the point* of
having a syntax. And i'm certainly OK with comment style like this:
/*
* some meaningful comment.
* :doc_marker:
*/
...
/* :end doc_marker: */
Or something to that effect. What i'm *not* in favor of is these markers
looking like part of a comment, rather than markers for doxygen.
--
Thanks,
Anatoly
