Merge pull request #799 from PowerGridModel/feature/columnar-data-c-a…

…pi-docs

improve C API documentation

power_grid_model_c/power_grid_model_c/include/power_grid_model_c/buffer.h

@@ -20,16 +20,16 @@ extern "C" {
 /**
  * @brief Create a buffer with certain size and component type.
  *
- * You can use this function to allocate a buffer.
+ * You can use this function to allocate a (row-based) component buffer.
  * You can also use your own allocation function to do that
- * with size and alignment got from PGM_meta_component_size() and PGM_meta_component_alignment().
+ * with size and alignment obtained from PGM_meta_component_size() and PGM_meta_component_alignment().
  * The buffer created by this function should be freed by PGM_destroy_buffer().
  *
  * It is recommended to call PGM_buffer_set_nan() after you create an input or update buffer.
  * In this way all the attributes will be set to NaN.
- * And if there is a new optional attribute added in the future.
- * You have garantee that your code is still compatible
- * because that optional attribute will be set to NaN and the default value will be used.
+ * Additionally, if there is a new optional attribute added in the future,
+ * compatibility with your code is guaranteed: that optional attribute will be set to NaN
+ * and the default value will be used.
  *
  * @param handle
  * @param component A component pointer.
@@ -41,7 +41,7 @@ PGM_API void* PGM_create_buffer(PGM_Handle* handle, PGM_MetaComponent const* com
 /**
  * @brief Destroy the buffer you created using PGM_create_buffer().
  *
- * NOTE: do not call this function on the buffer you created using your own function.
+ * NOTE: Do not call this function on the buffer you created using your own function.
  *
  * @param ptr The pointer to the buffer created using PGM_create_buffer().
  */

power_grid_model_c/power_grid_model_c/include/power_grid_model_c/dataset.h

@@ -140,7 +140,7 @@ PGM_API void PGM_destroy_dataset_const(PGM_ConstDataset* dataset);
  *     If the component is not uniform, indptr must point to an array of size (batch_size + 1).
  *         The values in the array must be not decreasing.
  *         And we must have indptr[0] = 0, indptr[batch_size] = total_elements.
- * @param data A void pointer to the row based buffer data or a nullptr for columnar data.
+ * @param data A void pointer to the row based buffer data or NULL for columnar data.
  * @return
  */
 PGM_API void PGM_dataset_const_add_buffer(PGM_Handle* handle, PGM_ConstDataset* dataset, char const* component,
@@ -185,7 +185,7 @@ PGM_API PGM_DatasetInfo const* PGM_dataset_writable_get_info(PGM_Handle* handle,
  * @param indptr A pointer to an array of indptr of a non-uniform component.
  *     If the component is uniform, indptr must be NULL.
  *     If the component is not uniform, indptr must point to an array of size (batch_size + 1).
- * @param data A void pointer to the row based buffer data or a nullptr for columnar data.
+ * @param data A void pointer to the row based buffer data or NULL for columnar data.
  * @return
  */
 PGM_API void PGM_dataset_writable_set_buffer(PGM_Handle* handle, PGM_WritableDataset* dataset, char const* component,
@@ -237,7 +237,7 @@ PGM_API void PGM_destroy_dataset_mutable(PGM_MutableDataset* dataset);
  *     If the component is not uniform, indptr must point to an array of size (batch_size + 1).
  *         The values in the array must be not decreasing.
  *         And we must have indptr[0] = 0, indptr[batch_size] = total_elements.
- * @param data A void pointer to the row based buffer data or a nullptr for columnar data.
+ * @param data A void pointer to the row based buffer data or NULL for columnar data.
  * @return
  */
 PGM_API void PGM_dataset_mutable_add_buffer(PGM_Handle* handle, PGM_MutableDataset* dataset, char const* component,