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
