Improve documentation in filter.h and filter.internal.h.

When the filter interface internals were split out into a new header file the documentation was not moved as it should have been.  Additionally some functions which should have been moved were left behind.

Move the documentation and functions to filter.internal.h and add more documentation.  Filters are a tricky subject so the more documentation the better.

Also add documentation for the user-facing filter functions in filter.h.

doc/xml/release.xml

@@ -154,6 +154,10 @@
                     <release-item>
                         <p>Simplify debug logging by allowing log functions to return <code>String</code> objects.</p>
                     </release-item>
+
+                    <release-item>
+                        <p>Improve documentation in <code>filter.h</code> and <code>filter.internal.h</code>.</p>
+                    </release-item>
                 </release-development-list>
             </release-core-list>
 

src/Makefile

@@ -206,7 +206,7 @@ common/io/filter/buffer.o: common/io/filter/buffer.c common/debug.h common/error
 common/io/filter/filter.o: common/io/filter/filter.c common/assert.h common/debug.h common/error.auto.h common/error.h common/io/filter/filter.h common/io/filter/filter.intern.h common/log.h common/logLevel.h common/memContext.h common/stackTrace.h common/type/buffer.h common/type/convert.h common/type/keyValue.h common/type/string.h common/type/variant.h common/type/variantList.h
 	$(CC) $(CFLAGS) -c common/io/filter/filter.c -o common/io/filter/filter.o
 
-common/io/filter/group.o: common/io/filter/group.c common/assert.h common/debug.h common/error.auto.h common/error.h common/io/filter/buffer.h common/io/filter/filter.h common/io/filter/group.h common/io/io.h common/log.h common/logLevel.h common/memContext.h common/stackTrace.h common/type/buffer.h common/type/convert.h common/type/keyValue.h common/type/list.h common/type/string.h common/type/variant.h common/type/variantList.h
+common/io/filter/group.o: common/io/filter/group.c common/assert.h common/debug.h common/error.auto.h common/error.h common/io/filter/buffer.h common/io/filter/filter.h common/io/filter/filter.intern.h common/io/filter/group.h common/io/io.h common/log.h common/logLevel.h common/memContext.h common/stackTrace.h common/type/buffer.h common/type/convert.h common/type/keyValue.h common/type/list.h common/type/string.h common/type/variant.h common/type/variantList.h
 	$(CC) $(CFLAGS) -c common/io/filter/group.c -o common/io/filter/group.o
 
 common/io/filter/size.o: common/io/filter/size.c common/debug.h common/error.auto.h common/error.h common/io/filter/filter.h common/io/filter/filter.intern.h common/io/filter/size.h common/log.h common/logLevel.h common/memContext.h common/stackTrace.h common/type/buffer.h common/type/convert.h common/type/keyValue.h common/type/string.h common/type/variant.h common/type/variantList.h

src/common/io/filter/filter.h

@@ -1,19 +1,12 @@
 /***********************************************************************************************************************************
 IO Filter Interface
 
-Two types of filters are implemented using this interface:  In and InOut.
+Filters can modify an i/o stream (e.g. GzipCompress, GzipDecompress), generate a result (e.g. IoSize, CryptoHash), or even do both.
 
-In filters accept input and produce a result, but do not modify the input.  An example is the IoSize filter which counts all bytes
-that pass through it.
+A filter is created using a constructor implemented by each filter (e.g. ioBufferNew).  Filter processing is managed by
+IoFilterGroup so the only user facing functions are ioFilterResult() and ioFilterType().
 
-InOut filters accept input and produce output (and perhaps a result).  Because the input/output buffers may not be the same size the
-filter must be prepared to accept the same input again (by implementing IoFilterInputSame) if the output buffer is too small to
-accept all processed data.  If the filter holds state even when inputSame is false then it may also implement IoFilterDone to
-indicate that the filter should be flushed (by passing NULL inputs) after all input has been processed.  InOut filters should strive
-to fill the output buffer as much as possible, i.e., if the output buffer is not full after processing then inputSame should be
-false.  An example is the IoBuffer filter which buffers data between unequally sized input/output buffers.
-
-Each filter has a type that allows it to be identified in the filter list.
+Information on implementing a filter is in filter.internal.h.
 ***********************************************************************************************************************************/
 #ifndef COMMON_IO_FILTER_FILTER_H
 #define COMMON_IO_FILTER_FILTER_H
@@ -26,19 +19,9 @@ typedef struct IoFilter IoFilter;
 #include "common/type/string.h"
 #include "common/type/variant.h"
 
-/***********************************************************************************************************************************
-Functions
-***********************************************************************************************************************************/
-void ioFilterProcessIn(IoFilter *this, const Buffer *input);
-void ioFilterProcessInOut(IoFilter *this, const Buffer *input, Buffer *output);
-IoFilter *ioFilterMove(IoFilter *this, MemContext *parentNew);
-
 /***********************************************************************************************************************************
 Getters
 ***********************************************************************************************************************************/
-bool ioFilterDone(const IoFilter *this);
-bool ioFilterInputSame(const IoFilter *this);
-bool ioFilterOutput(const IoFilter *this);
 const Variant *ioFilterResult(const IoFilter *this);
 const String *ioFilterType(const IoFilter *this);
 

src/common/io/filter/filter.intern.h

@@ -1,5 +1,19 @@
 /***********************************************************************************************************************************
 IO Filter Interface Internal
+
+Two types of filters are implemented using this interface:  In and InOut.
+
+In filters accept input and produce a result, but do not modify the input.  An example is the IoSize filter which counts all bytes
+that pass through it.
+
+InOut filters accept input and produce output (and perhaps a result).  Because the input/output buffers may not be the same size the
+filter must be prepared to accept the same input again (by implementing IoFilterInputSame) if the output buffer is too small to
+accept all processed data.  If the filter holds state even when inputSame is false then it may also implement IoFilterDone to
+indicate that the filter should be flushed (by passing NULL inputs) after all input has been processed.  InOut filters should strive
+to fill the output buffer as much as possible, i.e., if the output buffer is not full after processing then inputSame should be
+false.  An example is the IoBuffer filter which buffers data between unequally sized input/output buffers.
+
+Each filter has a type that allows it to be identified in the filter list.
 ***********************************************************************************************************************************/
 #ifndef COMMON_IO_FILTER_FILTER_INTERN_H
 #define COMMON_IO_FILTER_FILTER_INTERN_H
@@ -17,10 +31,26 @@ typedef Variant *(*IoFilterInterfaceResult)(const void *driver);
 
 typedef struct IoFilterInterface
 {
+    // Indicates that filter processing is done.  This is used for filters that have additional data to be flushed even after all
+    // input has been processed.  Compression and encryption filters will usually need to implement done.  If done is not
+    // implemented then it will always return true if all input has been consumed, i.e. if inputSame returns false.
     IoFilterInterfaceDone done;
+
+    // Processing function for filters that do not produce output.  Note that result must be implemented in this case (or else what
+    // would be the point.
     IoFilterInterfaceProcessIn in;
+
+    // Processing function for filters that produce output.  InOut filters will typically implement inputSame and may also implement
+    // done.
     IoFilterInterfaceProcessInOut inOut;
+
+    // InOut filters must be prepared for an output buffer that is too small to accept all the processed output.  In this case the
+    // filter must implement inputSame and set it to true when there is more output to be produced for a given input.  On the next
+    // call to inOut the same input will be passed along with a fresh output buffer with space for more processed output.
     IoFilterInterfaceInputSame inputSame;
+
+    // If the filter produces a result then this function must be implemented to return the result.  A result can be anything that
+    // is not processed output, e.g. a count of total bytes or a cryptographic hash.
     IoFilterInterfaceResult result;
 } IoFilterInterface;
 
@@ -29,6 +59,20 @@ typedef struct IoFilterInterface
 
 IoFilter *ioFilterNew(const String *type, void *driver, IoFilterInterface);
 
+/***********************************************************************************************************************************
+Functions
+***********************************************************************************************************************************/
+void ioFilterProcessIn(IoFilter *this, const Buffer *input);
+void ioFilterProcessInOut(IoFilter *this, const Buffer *input, Buffer *output);
+IoFilter *ioFilterMove(IoFilter *this, MemContext *parentNew);
+
+/***********************************************************************************************************************************
+Getters
+***********************************************************************************************************************************/
+bool ioFilterDone(const IoFilter *this);
+bool ioFilterInputSame(const IoFilter *this);
+bool ioFilterOutput(const IoFilter *this);
+
 /***********************************************************************************************************************************
 Macros for function logging
 ***********************************************************************************************************************************/

src/common/io/filter/group.c

@@ -6,6 +6,7 @@ IO Filter Group
 #include "common/assert.h"
 #include "common/debug.h"
 #include "common/io/filter/buffer.h"
+#include "common/io/filter/filter.intern.h"
 #include "common/io/filter/group.h"
 #include "common/io/io.h"
 #include "common/log.h"