Funtion name with variable part in doc/man7/ and doc/internal/man3/

[openssl.git] / doc / internal / man3 / DEFINE_SPARSE_ARRAY_OF.pod

diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
index 8afd48ec4d592a72d50dcb8bc60889b06a9dd793..60695266a76d5f074e79010b134aa55fb66dddff 100644 (file)
--- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
+++ b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
@@ -33,38 +33,46 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
 
 =head1 DESCRIPTION
 
+=begin comment
+
+POD is pretty good at recognising function names and making them appropriately
+bold...  however, when part of the function name is variable, we have to help
+the processor along
+
+=end comment
+
 SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
-B<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
-B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
-element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
-each function name begins with B<ossl_sa_TYPE_>. For example:
+I<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
+I<TYPE>. This will mean that a pointer to type I<TYPE> is stored in each
+element of a sparse array, the type is referenced by B<SPARSE_ARRAY_OF>(I<TYPE>)
+and each function name begins with B<ossl_sa_I<TYPE>_>. For example:
 
  TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
 
-ossl_sa_TYPE_num() returns the number of elements in I<sa> or 0 if I<sa> is
-NULL.
+B<ossl_sa_I<TYPE>_num>() returns the number of elements in I<sa> or 0 if I<sa>
+is NULL.
 
-ossl_sa_TYPE_get() returns element I<idx> in I<sa>, where I<idx> starts at
-zero. If I<idx> refers to a value that has not been set then NULL is
+B<ossl_sa_I<TYPE>_get>() returns element I<idx> in I<sa>, where I<idx> starts
+at zero. If I<idx> refers to a value that has not been set then NULL is
 returned.
 
-ossl_sa_TYPE_set() sets element I<idx> in I<sa> to I<value>, where I<idx>
+B<ossl_sa_I<TYPE>_set>() sets element I<idx> in I<sa> to I<value>, where I<idx>
 starts at zero. The sparse array will be resized as required.
 
-ossl_sa_TYPE_new() allocates a new empty sparse array.
+B<ossl_sa_I<TYPE>_new>() allocates a new empty sparse array.
 
-ossl_sa_TYPE_free() frees up the I<sa> structure. It does I<not> free up any
+B<ossl_sa_I<TYPE>_free>() frees up the I<sa> structure. It does I<not> free up any
 elements of I<sa>. After this call I<sa> is no longer valid.
 
-ossl_sa_TYPE_free_leaves() frees up the I<sa> structure and all of its
+B<ossl_sa_I<TYPE>_free_leaves>() frees up the I<sa> structure and all of its
 elements.  After this call I<sa> is no longer valid.
 
-ossl_sa_TYPE_doall() calls the function I<leaf> for each element in I<sa>
+B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa>
 in ascending index order. The index position, within the sparse array,
 of each item is passed as the first argument to the leaf function and a
 pointer to the associated value is is passed as the second argument.
 
-ossl_sa_TYPE_doall_arg() calls the function I<leaf> for each element in
+B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in
 I<sa> in ascending index order. The index position, within the sparse
 array, of each item is passed as the first argument to the leaf function,
 a pointer to the associated value is passed as the second argument and
@@ -77,9 +85,9 @@ Sparse arrays are an internal data structure and should B<not> be used by user
 applications.
 
 Care should be taken when accessing sparse arrays in multi-threaded
-environments.  The ossl_sa_TYPE_set operation can cause the internal structure
-of the sparse array to change which causes race conditions if the sparse array
-is accessed in a different thread.
+environments.  The B<ossl_sa_I<TYPE>_set>() operation can cause the internal
+structure of the sparse array to change which causes race conditions if the
+sparse array is accessed in a different thread.
 
 SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
 
@@ -90,21 +98,22 @@ OPENSSL_SA_num and OPENSSL_SA_set.
 
 =head1 RETURN VALUES
 
-ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
-if the passed sparse array is NULL.
+B<ossl_sa_I<TYPE>_num>() returns the number of elements in the sparse array or
+B<0> if the passed sparse array is NULL.
 
-ossl_sa_TYPE_get() returns a pointer to a sparse array element or NULL if
+B<ossl_sa_I<TYPE>_get>() returns a pointer to a sparse array element or NULL if
 the element has not be set.
 
-ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
+B<ossl_sa_I<TYPE>_set>() return B<1> on success and B<0> on error. In the latter
 case, the elements of the sparse array remain unchanged, although the internal
 structures might have.
 
-ossl_sa_TYPE_new() returns an empty sparse array or NULL if an error
+B<ossl_sa_I<TYPE>_new>() returns an empty sparse array or NULL if an error
 occurs.
 
-ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
-ossl_sa_TYPE_free_leaves() do not return values.
+B<ossl_sa_I<TYPE>_doall>(), B<ossl_sa_I<TYPE>_doall_arg>(),
+B<ossl_sa_I<TYPE>_free>() and B<ossl_sa_I<TYPE>_free_leaves>()
+do not return values.
 
 =head1 HISTORY