Add documentation in C++ class

Core/GDCore/Project/ObjectFolderOrObject.h

@@ -20,27 +20,89 @@ class ObjectsContainer;
 
 namespace gd {
 
+/**
+ * \brief Class representing a folder structure in order to organize objects
+ * in folders (to be used with an ObjectsContainer.)
+ *
+ * \see gd::ObjectsContainer
+ */
 class GD_CORE_API ObjectFolderOrObject {
  public:
+  /**
+   * \brief Default constructor creating an empty instance. Useful for the null
+   * object pattern.
+   */
   ObjectFolderOrObject();
+  virtual ~ObjectFolderOrObject();
+  /**
+   * \brief Constructor for creating an instance representing a folder.
+   */
   ObjectFolderOrObject(gd::String folderName_,
                        ObjectFolderOrObject* parent_ = nullptr);
+  /**
+   * \brief Constructor for creating an instance representing an object.
+   */
   ObjectFolderOrObject(gd::Object* object_,
                        ObjectFolderOrObject* parent_ = nullptr);
-  virtual ~ObjectFolderOrObject();
 
+  /**
+   * \brief Returns the object behind the instance.
+   */
   gd::Object& GetObject() const { return *object; }
 
+  /**
+   * \brief Returns true if the instance represents a folder.
+   */
   bool IsFolder() const { return !folderName.empty(); }
+  /**
+   * \brief Returns the name of the folder.
+   */
   gd::String GetFolderName() const { return folderName; }
+
+  /**
+   * \brief Set the folder name. Does nothing if called on an instance not
+   * representing a folder.
+   */
+  void SetFolderName(const gd::String& name) {
+    if (!IsFolder()) return;
+    folderName = name;
+  }
+
+  /**
+   * \brief Returns true if the instance contains the object with the given name
+   * (directly of indirectly through the children).
+   *
+   * Returns true if the instance represents the object with the given name or
+   * if any of the children does (recursive search).
+   */
   bool HasObjectNamed(const gd::String& name);
+
+  /**
+   * \brief Returns the number of children. Returns 0 if the instance represents
+   * an object.
+   */
   std::size_t GetChildrenCount() const {
     if (IsFolder()) return children.size();
     return 0;
   }
+  /**
+   * \brief Returns the child ObjectFolderOrObject at the given index.
+   */
   ObjectFolderOrObject& GetChildAt(std::size_t index);
+  /**
+   * \brief Returns the child ObjectFolderOrObject that represents the object
+   * with the given name. To use only if sure that the instance holds the object
+   * in its direct children (no recursive search).
+   *
+   * \note The equivalent method to get a folder by its name cannot be
+   * implemented because there is no unicity enforced on the folder name.
+   */
   ObjectFolderOrObject& GetObjectChild(const gd::String& name);
 
+  /**
+   * \brief Returns the parent of the instance. If the instance has no parent
+   * (root folder), the null object is returned.
+   */
   ObjectFolderOrObject& GetParent() {
     if (parent == nullptr) {
       return badObjectFolderOrObject;
@@ -48,37 +110,68 @@ class GD_CORE_API ObjectFolderOrObject {
     return *parent;
   };
 
+  /**
+   * \brief Moves a child from a position to a new one.
+   */
   void MoveChild(std::size_t oldIndex, std::size_t newIndex);
+  /**
+   * \brief Removes the given child from the instance's children. If the given
+   * child contains children of its own, does nothing.
+   */
   void RemoveFolderChild(gd::ObjectFolderOrObject& childToRemove);
-
-  void InsertObject(gd::Object* insertedObject);
-  void InsertObject(gd::Object* insertedObject, std::size_t position);
-  ObjectFolderOrObject& InsertNewFolder(const gd::String newFolderName,
-                                        std::size_t position);
-  bool IsADescendantOf(ObjectFolderOrObject& otherObjectFolderOrObject);
-
-  std::size_t GetChildPosition(ObjectFolderOrObject& child) const;
-
+  /**
+   * \brief Removes the child representing the object with the given name from
+   * the instance children and recursively does it for every folder children.
+   */
   void RemoveRecursivelyObjectNamed(const gd::String& name);
 
+  /**
+   * \brief Inserts an instance representing the given object at the end of the
+   * children.
+   */
+  void InsertObject(gd::Object* insertedObject);
+  /**
+   * \brief Inserts an instance representing the given object at the given
+   * position.
+   */
+  void InsertObject(gd::Object* insertedObject, std::size_t position);
+  /**
+   * \brief Inserts an instance representing a folder with the given name at the
+   * given position.
+   */
+  ObjectFolderOrObject& InsertNewFolder(const gd::String newFolderName,
+                                        std::size_t position);
+  /**
+   * \brief Returns true if the instance is a descendant of the given instance
+   * of ObjectFolderOrObject.
+   */
+  bool IsADescendantOf(ObjectFolderOrObject& otherObjectFolderOrObject);
+
+  /**
+   * \brief Returns the position of the given instance of ObjectFolderOrObject
+   * in the instance's children.
+   */
+  std::size_t GetChildPosition(ObjectFolderOrObject& child) const;
+  /**
+   * \brief Moves the given child ObjectFolderOrObject to the given folder at
+   * the given position.
+   */
   void MoveObjectFolderOrObjectToAnotherFolder(
       gd::ObjectFolderOrObject& objectFolderOrObject,
       gd::ObjectFolderOrObject& newParentFolder,
       std::size_t newPosition);
 
-  void RenameFolder(const gd::String& name) { folderName = name; }
-
   /** \name Saving and loading
    * Members functions related to saving and loading the objects of the class.
    */
   ///@{
   /**
-   * \brief Serialize the object folder or object.
+   * \brief Serialize the ObjectFolderOrObject instance.
    */
   void SerializeTo(SerializerElement& element) const;
 
   /**
-   * \brief Unserialize the object folder or object.
+   * \brief Unserialize the ObjectFolderOrObject instance.
    */
   void UnserializeFrom(gd::Project& project,
                        const SerializerElement& element,
@@ -86,16 +179,18 @@ class GD_CORE_API ObjectFolderOrObject {
   ///@}
 
  private:
-  gd::Object* object;  // Vide si folderName est pas vide.
-
-  // ou:
-
-  gd::String folderName;  // Vide is objectName est pas vide.
-  std::vector<std::unique_ptr<ObjectFolderOrObject>> children;
-  gd::ObjectFolderOrObject*
-      parent;  // nullptr if root folder, sinon pointeur vers le parent.
-
   static gd::ObjectFolderOrObject badObjectFolderOrObject;
+
+  gd::ObjectFolderOrObject*
+      parent;  // nullptr if root folder, points to the parent folder otherwise.
+
+  // Representing an object:
+  gd::Object* object;  // Empty if folderName is set.
+
+  // or representing a folder:
+  gd::String folderName;  // Empty if object is set.
+  std::vector<std::unique_ptr<ObjectFolderOrObject>>
+      children;  // Folder children.
 };
 
 }  // namespace gd

GDevelop.js/Bindings/Bindings.idl

@@ -401,12 +401,12 @@ interface ObjectFolderOrObject {
     boolean IsFolder();
     [Ref] gdObject GetObject();
     [Const, Ref] DOMString GetFolderName();
+    void SetFolderName([Const] DOMString name);
     boolean HasObjectNamed([Const] DOMString name);
     unsigned long GetChildrenCount();
     [Ref] ObjectFolderOrObject GetChildAt(unsigned long pos);
     [Ref] ObjectFolderOrObject GetObjectChild([Const] DOMString name);
     unsigned long GetChildPosition([Ref] ObjectFolderOrObject child);
-    void RenameFolder([Const] DOMString name);
     [Ref] ObjectFolderOrObject GetParent();
     [Ref] ObjectFolderOrObject InsertNewFolder([Const] DOMString name, unsigned long newPosition);
     void MoveObjectFolderOrObjectToAnotherFolder([Ref] ObjectFolderOrObject objectFolderOrObject, [Ref] ObjectFolderOrObject newParentFolder, unsigned long newPosition);

GDevelop.js/__tests__/Core.js

@@ -4638,7 +4638,7 @@ Array [
       const rootFolder = layout.getRootFolder();
       const subFolder = rootFolder.insertNewFolder('Enemies', 1);
       expect(subFolder.getFolderName()).toEqual('Enemies');
-      subFolder.renameFolder('Players');
+      subFolder.setFolderName('Players');
       expect(subFolder.getFolderName()).toEqual('Players');
       expect(subFolder.getParent()).toBe(rootFolder);
       expect(rootFolder.getChildrenCount()).toEqual(1);

GDevelop.js/types/gdobjectfolderorobject.js

@@ -4,12 +4,12 @@ declare class gdObjectFolderOrObject {
   isFolder(): boolean;
   getObject(): gdObject;
   getFolderName(): string;
+  setFolderName(name: string): void;
   hasObjectNamed(name: string): boolean;
   getChildrenCount(): number;
   getChildAt(pos: number): gdObjectFolderOrObject;
   getObjectChild(name: string): gdObjectFolderOrObject;
   getChildPosition(child: gdObjectFolderOrObject): number;
-  renameFolder(name: string): void;
   getParent(): gdObjectFolderOrObject;
   insertNewFolder(name: string, newPosition: number): gdObjectFolderOrObject;
   moveObjectFolderOrObjectToAnotherFolder(objectFolderOrObject: gdObjectFolderOrObject, newParentFolder: gdObjectFolderOrObject, newPosition: number): void;

newIDE/app/src/SceneEditor/index.js

@@ -948,7 +948,7 @@ export default class SceneEditor extends React.Component<Props, State> {
     // newName is supposed to have been already validated.
 
     if (objectFolderOrObject.isFolder()) {
-      objectFolderOrObject.renameFolder(newName);
+      objectFolderOrObject.setFolderName(newName);
       done(true);
       return;
     }