New upstream version 18.11

[deb_dpdk.git] / doc / guides / contributing / documentation.rst

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 4c85da7..c28a95c 100644 (file)
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -1,3 +1,6 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2018 The DPDK contributors
+
 .. _doc_guidelines:
 
 DPDK Documentation Guidelines
@@ -34,7 +37,6 @@ The main directories that contain files related to documentation are shown below
        |-- testpmd_app_ug
        |-- rel_notes
        |-- nics
-       |-- xen
        |-- ...
 
 
@@ -81,7 +83,7 @@ added to by the developer.
 * **API documentation**
 
   The API documentation explains how to use the public DPDK functions.
-  The `API index page <http://dpdk.org/doc/api/>`_ shows the generated API documentation with related groups of functions.
+  The `API index page <http://doc.dpdk.org/api/>`_ shows the generated API documentation with related groups of functions.
 
   The API documentation should be updated via Doxygen comments when new functions are added.
 
@@ -282,33 +284,21 @@ The additional guidelines below reiterate or expand upon those guidelines.
 Line Length
 ~~~~~~~~~~~
 
-* The recommended style for the DPDK documentation is to put sentences on separate lines.
-  This allows for easier reviewing of patches.
-  Multiple sentences which are not separated by a blank line are joined automatically into paragraphs, for example::
-
-     Here is an example sentence.
-     Long sentences over the limit shown below can be wrapped onto
-     a new line.
-     These three sentences will be joined into the same paragraph.
-
-     This is a new paragraph, since it is separated from the
-     previous paragraph by a blank line.
-
-  This would be rendered as follows:
+* Lines in sentences should be less than 80 characters and wrapped at
+  words. Multiple sentences which are not separated by a blank line are joined
+  automatically into paragraphs.
 
-     *Here is an example sentence.
-     Long sentences over the limit shown below can be wrapped onto
-     a new line.
-     These three sentences will be joined into the same paragraph.*
+* Lines in literal blocks **must** be less than 80 characters since
+  they are not wrapped by the document formatters and can exceed the page width
+  in PDF documents.
 
-     *This is a new paragraph, since it is separated from the
-     previous paragraph by a blank line.*
+  Long literal command lines can be shown wrapped with backslashes. For
+  example::
 
-
-* Long sentences should be wrapped at 120 characters +/- 10 characters. They should be wrapped at words.
-
-* Lines in literal blocks must by less than 80 characters since they aren't wrapped by the document formatters
-  and can exceed the page width in PDF documents.
+     testpmd -l 2-3 -n 4 \
+             --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
+             -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
+             --txd=1024 --rxd=1024
 
 
 Whitespace
@@ -625,19 +615,14 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
   .. code-block:: c
 
      /**
-      * Attach a new Ethernet device specified by arguments.
-      *
-      * @param devargs
-      *  A pointer to a strings array describing the new device
-      *  to be attached. The strings should be a pci address like
-      *  `0000:01:00.0` or **virtual** device name like `net_pcap0`.
-      * @param port_id
-      *  A pointer to a port identifier actually attached.
+      * Try to take the lock.
       *
+      * @param sl
+      *   A pointer to the spinlock.
       * @return
-      *  0 on success and port_id is filled, negative on error.
+      *   1 if the lock is successfully taken; 0 otherwise.
       */
-     int rte_eth_dev_attach(const char *devargs, uint8_t *port_id);
+     int rte_spinlock_trylock(rte_spinlock_t *sl);
 
 * Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
   For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
@@ -668,7 +653,7 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
        */
 
   In the API documentation the functions will be rendered as links, see the
-  `online section of the rte_ethdev.h docs <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above text.
+  `online section of the rte_ethdev.h docs <http://doc.dpdk.org/api/rte__ethdev_8h.html>`_ that contains the above text.
 
 * The ``@see`` keyword can be used to create a *see also* link to another file or library.
   This directive should be placed on one line at the bottom of the documentation section.