Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1645090

[PATCH 21/31] flexible-arrays.txt: standardize document format

From Mauro Carvalho Chehab <mchehab@s-opensource.com>
Newsgroups linux.kernel
Subject [PATCH 21/31] flexible-arrays.txt: standardize document format
Date 2017-05-19 03:50 +0200
Message-ID <tIFdg-3gE-29@gated-at.bofh.it> (permalink)
References <tIETT-39a-3@gated-at.bofh.it>
Organization linux.* mail to news gateway

Show all headers | View raw

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- use :Author: and :Updated: markups;
- use proper markup for the document title;
- mark the literal-blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/flexible-arrays.txt | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/Documentation/flexible-arrays.txt b/Documentation/flexible-arrays.txt
index df904aec9904..45aec4d354f7 100644
--- a/Documentation/flexible-arrays.txt
+++ b/Documentation/flexible-arrays.txt
@@ -1,6 +1,8 @@
 Using flexible arrays in the kernel
-Last updated for 2.6.32
-Jonathan Corbet <corbet@lwn.net>
+===================================
+
+:Updated: Last updated for 2.6.32
+:Author: Jonathan Corbet <corbet@lwn.net>
 
 Large contiguous memory allocations can be unreliable in the Linux kernel.
 Kernel programmers will sometimes respond to this problem by allocating
@@ -26,7 +28,7 @@ operation.  It's also worth noting that flexible arrays do no internal
 locking at all; if concurrent access to an array is possible, then the
 caller must arrange for appropriate mutual exclusion.
 
-The creation of a flexible array is done with:
+The creation of a flexible array is done with::
 
     #include <linux/flex_array.h>
 
@@ -40,14 +42,14 @@ argument is passed directly to the internal memory allocation calls.  With
 the current code, using flags to ask for high memory is likely to lead to
 notably unpleasant side effects.
 
-It is also possible to define flexible arrays at compile time with:
+It is also possible to define flexible arrays at compile time with::
 
     DEFINE_FLEX_ARRAY(name, element_size, total);
 
 This macro will result in a definition of an array with the given name; the
 element size and total will be checked for validity at compile time.
 
-Storing data into a flexible array is accomplished with a call to:
+Storing data into a flexible array is accomplished with a call to::
 
     int flex_array_put(struct flex_array *array, unsigned int element_nr,
     		       void *src, gfp_t flags);
@@ -63,7 +65,7 @@ running in some sort of atomic context; in this situation, sleeping in the
 memory allocator would be a bad thing.  That can be avoided by using
 GFP_ATOMIC for the flags value, but, often, there is a better way.  The
 trick is to ensure that any needed memory allocations are done before
-entering atomic context, using:
+entering atomic context, using::
 
     int flex_array_prealloc(struct flex_array *array, unsigned int start,
 			    unsigned int nr_elements, gfp_t flags);
@@ -73,7 +75,7 @@ defined by start and nr_elements has been allocated.  Thereafter, a
 flex_array_put() call on an element in that range is guaranteed not to
 block.
 
-Getting data back out of the array is done with:
+Getting data back out of the array is done with::
 
     void *flex_array_get(struct flex_array *fa, unsigned int element_nr);
 
@@ -89,7 +91,7 @@ involving that number probably result from use of unstored array entries.
 Note that, if array elements are allocated with __GFP_ZERO, they will be
 initialized to zero and this poisoning will not happen.
 
-Individual elements in the array can be cleared with:
+Individual elements in the array can be cleared with::
 
     int flex_array_clear(struct flex_array *array, unsigned int element_nr);
 
@@ -97,7 +99,7 @@ This function will set the given element to FLEX_ARRAY_FREE and return
 zero.  If storage for the indicated element is not allocated for the array,
 flex_array_clear() will return -EINVAL instead.  Note that clearing an
 element does not release the storage associated with it; to reduce the
-allocated size of an array, call:
+allocated size of an array, call::
 
     int flex_array_shrink(struct flex_array *array);
 
@@ -106,12 +108,12 @@ This function works by scanning the array for pages containing nothing but
 FLEX_ARRAY_FREE bytes, so (1) it can be expensive, and (2) it will not work
 if the array's pages are allocated with __GFP_ZERO.
 
-It is possible to remove all elements of an array with a call to:
+It is possible to remove all elements of an array with a call to::
 
     void flex_array_free_parts(struct flex_array *array);
 
 This call frees all elements, but leaves the array itself in place.
-Freeing the entire array is done with:
+Freeing the entire array is done with::
 
     void flex_array_free(struct flex_array *array);
 
-- 
2.9.4

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
  [PATCH 16/31] DMA-attributes.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
  [PATCH 27/31] intel_txt.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
  [PATCH 26/31] hwspinlock.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
  [PATCH 13/31] digsig.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:30 +0200
  [PATCH 19/31] efi-stub.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 28/31] Intel-IOMMU.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 06/31] cgroup-v2.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
    Re: [PATCH 06/31] cgroup-v2.txt: standardize document format Tejun Heo <tj@kernel.org> - 2017-05-19 17:00 +0200
  [PATCH 03/31] btmrvl.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 22/31] futex-requeue-pi.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 08/31] clk.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 07/31] circular-buffers.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 12/31] dcdbas.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 25/31] hw_random.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 21/31] flexible-arrays.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 01/31] bcache.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 04/31] bus-virt-phys-mapping.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 23/31] gcc-plugins.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
    Re: [PATCH 23/31] gcc-plugins.txt: standardize document format Kees Cook <keescook@google.com> - 2017-05-24 19:40 +0200
      Re: [PATCH 23/31] gcc-plugins.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-24 22:20 +0200
  [PATCH 09/31] cpu-load: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 24/31] highuid.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 17/31] DMA-ISA-LPC.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 18/31] debugging-via-ohci1394.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 05/31] cachetlb.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 10/31] cputopology.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 02/31] bt8xxgpio.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 15/31] DMA-API-HOWTO.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 11/31] crc32.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 20/31] eisa.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200
  [PATCH 14/31] DMA-API.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:50 +0200

csiph-web