doc pntrAddElement

Author: wlammen

src/mmdata.h

@@ -849,6 +849,23 @@ long pntrRevInstr(long start_position, const pntrString *string1,
 flag pntrEq(const pntrString *sout, const pntrString *sin);
 
 /* Add a single null string element to a pntrString - faster than pntrCat */
+/*!
+ * \fn temp_pntrString *pntrAddElement(const pntrString *g)
+ * \param[in] g points to the first element of a NULL terminated array in a
+ *   \ref block.
+ * \return a copy of \p g, the terminal NULL replaced with a \ref vstring ""
+ *   followed by NULL.
+ * \attention   
+ *   - the pointers in \p g are copied to the result.  If some of them
+ *     reference allocated memory, check for possible double free, for example.
+ *   - a pointer to constant data is padded to the right.  The refernced memory
+ *     must not be overwritten.
+ * \post 
+ *   - the elements of \p g are duplicated.
+ *   - a pointer to a NUL byte ("") constant is padded to the right.  Make sure
+ *     the referenced memory is never overwritten.
+ * \bug a pointer to constant data is added as a writeable void*.
+ */
 temp_pntrString *pntrAddElement(const pntrString *g);
 
 /* Add a single null pntrString element to a pntrString - faster than pntrCat */