finalise interface & documentation

Signed-off-by: Folling <mail@folling.io>

include/ikarus/folders/property_folder.h

@@ -1,22 +1,158 @@
 #pragma once
 
-#include <ikarus/id.h>
+/// \file property_folder.h
+/// \author Folling <folling@ikarus.world>
+
 #include <ikarus/macros.h>
 
-/// \file property_folder.h
-/// \author Folling <mail@folling.io>
-
-/// \addtogroup folder Folders
+/// \addtogroup properties Properties
 /// @{
 
 IKARUS_BEGIN_HEADER
 
 /// \brief A property folder, storing properties and other property folders.
-/// \remark Property folders are scoped to the blueprint or entity they are associated with.
-struct IkarusPropertyFolder {
-    /// \private \brief The id of the property folder.
-    IkarusId id;
-};
+struct IkarusPropertyFolder;
+
+/// \brief Creates a property folder.
+/// \param project The project the property folder is part of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param parent The parent folder of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param position The position of the property folder in the parent folder. \see #FolderPosition
+/// \pre \li Must be within bounds for the parent folder.
+/// \param name The name of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must not be empty.
+/// \return The created property folder or null if an error occurs.
+/// \remark Must be freed using #ikarus_free.
+IKA_API IkarusPropertyFolder * ikarus_property_folder_create(
+    struct IkarusProject * project, IkarusPropertyFolder * parent, size_t position, char const * name
+);
+
+/// \brief Copies a property folder.
+/// \details Creates a copy of the property folder without its children.
+/// \param property_folder The property folder to copy.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param parent The parent folder of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param position The position of the property folder in the parent folder. \see #FolderPosition
+/// \pre \li Must be within bounds for the parent folder.
+/// \param name The name of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must not be empty.
+/// \return The created property folder or null if an error occurs.
+/// \remark Must be freed using #ikarus_free.
+IKA_API IkarusPropertyFolder * ikarus_property_folder_copy(
+    IkarusPropertyFolder * property_folder, IkarusPropertyFolder * parent, size_t position, char const * name
+);
+
+/// \brief Deletes a property folder and all its children
+/// \param property_folder The property folder to delete.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param keep_children If true, the children of the property folder will be moved to the parent folder.
+IKA_API void ikarus_property_folder_delete(IkarusPropertyFolder * property_folder, bool keep_children);
+
+/// \brief Gets the project of a property folder.
+/// \param property_folder The property folder to get the project of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The project of the property folder or null if an error occurs.
+IKA_API struct IkarusProject * ikarus_property_folder_get_project(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the property source of a property folder.
+/// \param property_folder The property folder to get the property source of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The property source of the property folder or null if an error occurs.
+/// \remark Must be freed using #ikarus_free.
+IKA_API struct IkarusPropertySource * ikarus_property_folder_get_source(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the parent folder of a property folder.
+/// \param property_folder The property folder to get the parent folder of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The parent folder of the property folder or null if an error occurs.
+IKA_API struct IkarusPropertyFolder * ikarus_property_folder_get_parent(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the position of a property folder within its parent folder.
+/// \param property_folder The property folder to get the position of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The position of the property folder or undefined if an error occurs.
+IKA_API size_t ikarus_property_folder_get_position(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the name of a property folder.
+/// \param property_folder The property folder to get the name of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The name of the property folder or null if an error occurs.
+/// \remark The returned pointer is valid until the property folder is freed but may be invalidated by other operations.
+IKA_API char const * ikarus_property_folder_get_name(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the number of children of a property folder.
+/// \param property_folder The property folder to get the number of children of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \return The number of children or undefined if an error occurs.
+IKA_API size_t ikarus_property_folder_get_child_count(IkarusPropertyFolder const * property_folder);
+
+/// \brief Gets the children of a property folder.
+/// \param property_folder The property folder to get the children of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param children_out The buffer to write the children to.
+/// \pre \li Must not be null.
+/// \param children_out_size The size of the buffer.
+IKA_API void ikarus_property_folder_get_children(
+    IkarusPropertyFolder const * property_folder, struct IkarusPropertyTreeItem ** children_out, size_t children_out_size
+);
+
+/// \brief Sets the parent folder of an property folder.
+/// \param property_folder The property folder to set the parent folder of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param new_parent The new parent folder of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param new_position The new position of the property folder in the parent folder. \see #FolderPosition
+/// \pre \li Must be within bounds for the parent folder.
+/// \remark This adjusts the positions of old and new siblings.
+IKA_API void ikarus_property_folder_set_parent(
+    IkarusPropertyFolder * property_folder, struct IkarusPropertyFolder * new_parent, size_t new_position
+);
+
+/// \brief Sets the position of an property folder within its parent folder.
+/// \param property_folder The property folder to set the position of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param new_position The new position of the property folder. \see #FolderPosition
+/// \pre \li Must be within bounds for the parent folder.
+/// \remark This adjusts the positions of siblings.
+IKA_API void ikarus_property_folder_set_position(IkarusPropertyFolder * property_folder, size_t new_position);
+
+/// \brief Sets the name of an property folder.
+/// \param property_folder The property folder to set the name of.
+/// \pre \li Must not be null.
+/// \pre \li Must exist.
+/// \param new_name The new name of the property folder.
+/// \pre \li Must not be null.
+/// \pre \li Must not be empty.
+IKA_API void ikarus_property_folder_set_name(IkarusPropertyFolder * property_folder, char const * new_name);
+
+/// \brief Converts a property folder to a generic folder.
+/// \param property_folder The property folder to convert.
+/// \return The constructed folder, representing the property folder.
+IKA_API struct IkarusFolder * ikarus_property_folder_to_folder(IkarusPropertyFolder const * property_folder);
+
+/// \brief Converts a property folder to an object.
+/// \param property_folder The property folder to convert.
+/// \return The constructed object, representing the property folder.
+IKA_API struct IkarusObject * ikarus_property_folder_to_object(IkarusPropertyFolder const * property_folder);
 
 IKARUS_END_HEADER