Clean up Doxygen comments

Author: jimmysoda

source/pdal/capi/Forward.h

@@ -40,19 +40,19 @@ namespace pdal
 
 #endif /* __cplusplus */
 
-/// A pointer to a C++ pdal::capi::PDALDimTypeList
+/// A pointer to a dimension type list
 typedef void* PDALDimTypeListPtr;
 
-/// A pointer to a C++ pdal::capi::Pipeline object
+/// A pointer to a pipeline
 typedef void* PDALPipelinePtr;
 
-/// A pointer to a C++ pdal::PointLayout
+/// A pointer to a point layout
 typedef void* PDALPointLayoutPtr;
 
-/// A pointer to a C++ pdal::capi::PointView object
+/// A pointer to point view
 typedef void* PDALPointViewPtr;
 
-/// A pointer to a C++ pdal::capi::PointViewIterator object
+/// A pointer to a point view iterator
 typedef void* PDALPointViewIteratorPtr;
 
 #endif /* PDAL_CAPI_FORWARD_H */

source/pdal/capi/Pipeline.h

@@ -113,6 +113,10 @@ namespace pdal
 			/**
 			 * Gets the resulting point views from a pipeline execution.
 			 * 
+			 * @note The caller obtains ownership of the point view iterator pointed by the
+			 * returned value and its associated point view collection. Use PDALDisposePointViewIterator
+			 * to free these data structures.
+			 * 
 			 * @param pipeline The pipeline
 			 * @return A pointer to a point view collection or nullptr if no point views are available
 			 */

source/pdal/capi/PointView.h

@@ -91,6 +91,9 @@ namespace pdal
 
 			/**
 			 * Returns the point layout for the provided point `view`.
+			 *
+			 * @note This point view retains ownership of the
+			 * layout pointed by the return value. Do not free the returned pointer.
 			 * 
 			 * @param view The point view
 			 * @return The point layout

source/pdal/capi/PointViewIterator.h

@@ -13,7 +13,7 @@ namespace pdal
 {
 	namespace capi
 	{
-		class PDAL_C_API PointViewIterator
+		class PointViewIterator
 		{
 		public:
 			PointViewIterator(const pdal::PointViewSet& views);
@@ -32,13 +32,39 @@ namespace pdal
 #include <stdbool.h> // for bool
 #endif /* __cplusplus */
 
-			PDAL_C_API bool PDALHasNextPointView(PDALPointViewIteratorPtr collection);
+			/**
+			 * Returns whether another point view is available in the provided iterator.
+			 * 
+			 * @param itr A pointer to the point view iterator
+			 * @return Whether another point view is available
+			 */
+			PDAL_C_API bool PDALHasNextPointView(PDALPointViewIteratorPtr itr);
 
-			PDAL_C_API PDALPointViewPtr PDALGetNextPointView(PDALPointViewIteratorPtr collection);
+			/**
+			 * Returns the next available point view in the provided iterator.
+			 *
+			 * @note The caller obtains ownership of the data structure pointed by the returned value.
+			 * Use PDALDisposePointView to free the point view data structure.
+			 * 
+			 * @param itr A pointer to the point view iterator
+			 * @return The next point view in the iterator or NULL if none available
+			 */
+			PDAL_C_API PDALPointViewPtr PDALGetNextPointView(PDALPointViewIteratorPtr itr);
 
-			PDAL_C_API void PDALResetPointViewIterator(PDALPointViewIteratorPtr collection);
+			/**
+			 * Resets the provided point view iterator to its starting position.
+			 * 
+			 * @param itr A pointer to the point view iterator
+			 */
+			PDAL_C_API void PDALResetPointViewIterator(PDALPointViewIteratorPtr itr);
+
+			/**
+			 * Disposes the provided point view iterator.
+			 * 
+			 * @param itr A pointer to the point view iterator
+			 */
+			PDAL_C_API void PDALDisposePointViewIterator(PDALPointViewIteratorPtr itr);
 
-			PDAL_C_API void PDALDisposePointViewIterator(PDALPointViewIteratorPtr collection);
 #ifdef __cplusplus
 		}
 	}