Update Doxygen documentation for C API functions

Author: jimmysoda

source/pdal/capi/Pipeline.h

@@ -118,7 +118,7 @@ namespace pdal
 			 * 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
+			 * @return A pointer to a point view collection or NULL if no point views are available
 			 */
 			PDAL_C_API PDALPointViewIteratorPtr PDALGetPointViews(PDALPipelinePtr pipeline);
 

source/pdal/capi/PointLayout.h

@@ -24,19 +24,57 @@ namespace pdal
 
 			PDAL_C_API size_t PDALGetDimTypeInterpretationName(PDALDimType dim, char *name, size_t size);
 
+			/**
+			 * Returns the list of dimension types used by the provided `layout`.
+			 * 
+			 * @return The caller obtains ownership of the data structure referenced by the returned pointer.
+			 * Use PDALDisposeDimTypeList from DimTypes.h to free the data structure.
+			 * 
+			 * @param layout A pointer to the layout
+			 * @return A pointer to the dimension type list or NULL if the `layout` is NULL
+			 */
 			PDAL_C_API PDALDimTypeListPtr PDALGetPointLayoutDimTypes(PDALPointLayoutPtr layout);
 
 			PDAL_C_API void PDALDisposeDimTypeList(PDALDimTypeListPtr types);
 
+			/**
+			 * Finds the dimension type identified by the provided `name` in a `layout`.
+			 * 
+			 * @param layout A pointer to the layout
+			 * @param name The name of the dimension type, i.e., the string representation of its ID
+			 * @return The matching dimension type,
+			 *         or the value returned by PDALGetInvalidDimType from DimTypes.h if none found
+			 */
 			PDAL_C_API PDALDimType PDALFindDimType(PDALPointLayoutPtr layout, const char *name);
 
+			/**
+			 * Returns the byte size of a dimension type value within a `layout`.
+			 * 
+			 * @param layout A pointer to the layout
+			 * @param name The dimension type name
+			 * @return The dimension type byte size,
+			 *         or zero if the layout is NULL, the name is NULL, or the dimension type is not found
+			 */
 			PDAL_C_API size_t PDALGetDimSize(PDALPointLayoutPtr layout, const char *name);
 
+			/**
+			 * Returns the byte offset of a dimension type within a `layout`.
+			 *
+			 * @param layout A pointer to the layout
+			 * @param name The dimension type name
+			 * @return The dimension type offset,
+			 *         or zero if the layout is NULL, the name is NULL, or the dimension type is not found
+			 */
 			PDAL_C_API size_t PDALGetDimPackedOffset(PDALPointLayoutPtr layout, const char *name);
 
+			/**
+			 * Returns the byte size of a point in the provided `layout`.
+			 * 
+			 * @param layout A pointer to the layout
+			 * @return The byte size of a point in the layout or zero if the layout is NULL
+			 */
 			PDAL_C_API size_t PDALGetPointSize(PDALPointLayoutPtr layout);
 
-
 #ifdef __cplusplus
 		} // extern "C"
 	} // namespace capi

source/pdal/capi/PointView.h

@@ -41,7 +41,7 @@ namespace pdal
 			 * @see pdal::PointView::size
 			 * 
 			 * @param view The point view
-			 * @return The number of points
+			 * @return The number of points or zero if `view` is NULL
 			 */
 			PDAL_C_API uint64_t PDALGetPointViewSize(PDALPointViewPtr view);
 
@@ -51,7 +51,7 @@ namespace pdal
 			 * @see pdal::PointView::empty
 			 * 
 			 * @param view The point view
-			 * @return Whether the point view is empty
+			 * @return Whether the point view is empty or `false` if `view` is NULL
 			 */
 			PDAL_C_API bool PDALIsPointViewEmpty(PDALPointViewPtr view);
 
@@ -61,7 +61,7 @@ namespace pdal
 			 * @see pdal::PointView::makeNew
 			 * 
 			 * @param view The original point view
-			 * @return A pointer to the new point view
+			 * @return A pointer to the new point view or NULL if `view` is NULL
 			 */
 			PDAL_C_API PDALPointViewPtr PDALClonePointView(PDALPointViewPtr view);
 
@@ -74,6 +74,7 @@ namespace pdal
 			 * @param[out] proj The buffer used to hold the resulting proj4 projection string
 			 * @param size The size of the proj4 projection string buffer
 			 * @return The size of the resulting proj4 projection string
+			 *         or zero if the `proj` buffer is NULL or the buffer `size` is zero
 			 */
 			PDAL_C_API size_t PDALGetPointViewProj4(PDALPointViewPtr view, char *proj, size_t size);
 
@@ -86,6 +87,7 @@ namespace pdal
 			 * @param size The size of the wkt projection string buffer
 			 * @param pretty Whether to enhance the formatting of the resulting WKT string
 			 * @return The size of the resulting WKT projection string
+			 *         or zero if the `wkt` buffer is NULL or the buffer `size` is zero
 			 */
 			PDAL_C_API size_t PDALGetPointViewWkt(PDALPointViewPtr view, char *wkt, size_t size, bool pretty);
 
@@ -96,7 +98,7 @@ namespace pdal
 			 * layout pointed by the return value. Do not free the returned pointer.
 			 * 
 			 * @param view The point view
-			 * @return The point layout
+			 * @return The point layout or NULL if `view` is NULL
 			 */
 			PDAL_C_API PDALPointLayoutPtr PDALGetPointViewLayout(PDALPointViewPtr view);
 
@@ -109,7 +111,8 @@ namespace pdal
 			 * @param dims List of dimensions to retrieve
 			 * @param idx Index of point to get
 			 * @param[out] buf Pointer to buffer to fill
-			 * @return The size of the point stored in `buf`
+			 * @return The size of the retrieved point
+			 *         or zero if view` is NULL, `dims` is NULL, `buf` is NULL, or `idx` is out of bounds
 			 */
 			PDAL_C_API size_t PDALGetPackedPoint(PDALPointViewPtr view, PDALDimTypeListPtr dims, PDALPointId idx, char *buf);
 
@@ -123,6 +126,7 @@ namespace pdal
 			 * @param idx Index of point to get
 			 * @param[out] buf Pointer to buffer to fill
 			 * @return The size of the points stored in `buf`
+			 *         or zero if `view` is NULL, `dims` is NULL, or `buf` is NULL
 			 */
 			PDAL_C_API uint64_t PDALGetAllPackedPoints(PDALPointViewPtr view, PDALDimTypeListPtr dims, char *buf);
 

source/pdal/capi/PointViewIterator.h

@@ -36,7 +36,7 @@ namespace pdal
 			 * 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
+			 * @return Whether another point view is available or `false` if `itr` is NULL
 			 */
 			PDAL_C_API bool PDALHasNextPointView(PDALPointViewIteratorPtr itr);