* docs/: Add docs for ne_strhash, ne_vstrhash.

2 files changed, 108 insertions, 1 deletions

diff --git a/doc/manual.xml b/doc/manual.xml
index 311cdac..9fdfee5 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -65,6 +65,7 @@
 <!ENTITY refbufapp SYSTEM "ref/bufapp.xml">
 <!ENTITY refbufdest SYSTEM "ref/bufdest.xml">
 <!ENTITY refbufutil SYSTEM "ref/bufutil.xml">
+<!ENTITY refhash SYSTEM "ref/hash.xml">
 <!ENTITY reftok SYSTEM "ref/tok.xml">
 <!ENTITY refshave SYSTEM "ref/shave.xml">
 <!ENTITY refvers SYSTEM "ref/vers.xml">
@@ -87,7 +88,7 @@
       </personname>
       <email>neon@lists.manyfish.co.uk</email>
     </author>
-    <copyright><year>2001-2008</year><holder>Joe Orton</holder></copyright>
+    <copyright><year>2001-2021</year><holder>Joe Orton</holder></copyright>
 
     <legalnotice>
 
@@ -170,6 +171,7 @@ ignoring the WebDAV support if desired.</para>
     &refbufutil; <!-- ne_buffer_clear -->
     &refbufcr; <!-- ne_buffer_create -->
     &refbufdest; <!-- ne_buffer_destroy -->
+    &refhash; <!-- ne_strhash -->
     &referr; <!-- ne_get_error -->
     &refgetst; <!-- ne_get_status -->
     &reffeat; <!-- ne_has_support -->
diff --git a/doc/ref/hash.xml b/doc/ref/hash.xml
new file mode 100644
index 0000000..7cfd00b
--- /dev/null
+++ b/doc/ref/hash.xml
@@ -0,0 +1,105 @@
+    <refentry id="refhash">
+
+      <refmeta>
+	<refentrytitle>ne_strhash</refentrytitle>
+	<manvolnum>3</manvolnum>
+      </refmeta>
+
+      <refnamediv>
+	<refname id="ne_strash">ne_strhash</refname>
+	<refpurpose>string hash interface</refpurpose>
+      </refnamediv>
+      
+      <refsynopsisdiv>
+
+	<funcsynopsis>
+          <funcsynopsisinfo>#include &lt;ne_string.h&gt;</funcsynopsisinfo>
+
+	  <funcprototype>
+	    <funcdef>char *<function>ne_strhash</function></funcdef>
+	    <paramdef>unsigned int <parameter>flags</parameter></paramdef>
+	    <paramdef><parameter>...</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>char *<function>ne_vstrhash</function></funcdef>
+	    <paramdef>unsigned int <parameter>flags</parameter></paramdef>
+	    <paramdef>va_list <parameter>ap</parameter></paramdef>
+	  </funcprototype>
+        </funcsynopsis>
+
+      </refsynopsisdiv>
+
+      <refsect1>
+	<title>Description</title>
+
+	<para>The <function>ne_strhash</function> and
+	<function>ne_vstrhash</function> functions can be used to
+	create hashes.  The varargs argument list must be <type>const
+	char *</type> strings followed by a &null; terminator.  The
+	<parameter>flags</parameter> argument must select exactly one
+	hash algorithm from the list below, which can be optionally
+	bitwise-ORed with one of the formatting option.</para>
+
+        <refsect2>
+          <title>Hash algorithms</title>
+        
+        <para>The following hash algorithms are available:
+	<variablelist>
+	  <varlistentry>
+            <term><constant>NE_HASH_MD5</constant></term>
+	    <listitem><simpara>MD5</simpara></listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_HASH_SHA256</constant></term>
+	    <listitem><simpara>SHA-256 (SHA-2)</simpara></listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_HASH_SHA512</constant></term>
+	    <listitem><simpara>SHA-512 (SHA-2)</simpara></listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_HASH_SHA256_256</constant></term>
+	    <listitem><simpara>SHA-512/256 (SHA-2)</simpara></listitem>
+	  </varlistentry>
+        </variablelist>
+
+        </para></refsect2>
+        
+        <refsect2>
+          <title>Formatting options</title>
+          
+          <para>By default, the hash is returned as a hexadecimal
+          lower-case character string. The following formatting
+          options are available:
+        
+	<variablelist>
+	  <varlistentry>
+            <term><constant>NE_HASH_COLON</constant></term>
+	    <listitem><simpara>colon-separated hex pairs, e.g. <literal>"aa:11:22..."</literal> </simpara></listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_HASH_SPACE</constant></term>
+	    <listitem><simpara>space-separated hex pairs, e.g. <literal>"aa 11 22..."</literal></simpara></listitem>
+	  </varlistentry>
+          </variablelist></para>
+
+        </refsect2>
+        
+      </refsect1>
+
+      <refsect1>
+	<title>Return value</title>
+
+        <para>The return value is the ASCII hexadecimal representation
+        of the hash as a malloc-allocated, NUL-terminated string, or
+        &null; if the hash cannot be created.  The string length is
+        determined by the hash algorithm (and formatting options
+        used).  Support for hash algorithms is specific to the SSL
+        toolkit with which &neon; is compiled.  Some systems will
+        further restrict hash availability at runtime, e.g. due to
+        FIPS mode.</para>
+
+      </refsect1>
+
+    </refentry>