doc: added basic documentation for elektraDocCommit
Related to issue
@@ -533,6 +533,38 @@ int elektraDocGet (Plugin * handle, KeySet * returned, Key * parentKey);
*/
int elektraDocSet (Plugin * handle, KeySet * returned, Key * parentKey);
+/**
+ * @brief Make changes to storage permanent.
+ *
+ * Once the content of @p returned has been stored, the changes need
+ * to be made permanent and visible to other users, which is done by this function.
+ *
+ * It is called by kdbSet() if the plugin implementing it fulfills the `commit` role.
+ *
+ * @pre The keyset @p returned holds all stored keys which must be made permanent for this keyset.
+ * The keyset is sorted and rewinded.
+ *
+ * @pre The @p parentKey is the key which is the ancestor for all other keys in the
+ * keyset. The first key of the keyset @p returned has the same keyname.
+ * The name of the parentKey marks the mountpoint.
+ *
+ * @post the storage changes made by the plugins previously called by kdbSet() will be made permanent.
+ *
+ * @see kdbSet() for caller.
+ *
+ * @param handle contains internal information of the plugin
+ * @param returned contains a keyset with relevant keys
+ * @param parentKey contains the location of the relevant keys within the key database.
+ *
+ * @retval 1 on success
+ * @retval 0 on success without any changes
+ * @retval -1 on failure. The cause of the error needs to be entered into parentKey,
+ * ksGetCursor() needs to point to the position where the error appeared. The error
+ * can be specified using #ELEKTRA_SET_ERROR. #ELEKTRA_ADD_WARNING can be used to
+ * add warnings for the user.
+ *
+ * @ingroup plugin
+ */
int elektraDocCommit (Plugin * handle, KeySet * returned, Key * parentKey);
/**
