Add API reference documentation in doc folder

Add custom script that generates markdown wiki from yaml documentation

doc/BgImage.yml

@@ -0,0 +1,21 @@
+title: BgImage
+filename: LDtkLoader/Level.hpp
+structs:
+  - name: BgImage
+    desc: Contains information about the Level background image.
+    fields:
+      path:
+        decl: ldtk::FilePath ldtk::Level::BgImage::path
+        desc: The relative path to the background image file.
+
+      crop:
+        decl: ldtk::IntRect ldtk::Level::BgImage::crop
+        desc: The cropped sub rectangle of the displayed image.
+
+      pos:
+        decl: ldtk::IntPoint ldtk::Level::BgImage::pos
+        desc: The position of the top left corner of the background image in the level.
+
+      scale:
+        decl: ldtk::FloatPoint ldtk::Level::BgImage::scale
+        desc: The scale of the background image.

doc/DataTypes.yml

@@ -0,0 +1,209 @@
+title: DataTypes
+filename: LDtkLoader/DataTypes.hpp
+classes:
+  - name: FilePath
+    desc: A string that contains file path information.
+    ctor:
+      - decl: ldtk::FilePath::FilePath()
+        desc: Default constructor. Constructs an empty FilePath.
+      - decl: ldtk::FilePath::FilePath(const std::string&)
+        desc: Construct a FilePath from a valid provided string.
+    methods:
+      directory:
+        - decl: ldtk::FilePath::directory() const -> std::string
+          desc: Returns the path to the directory containing the file.
+
+      filename:
+        - decl: ldtk::FilePath::filename() const -> std::string
+          desc: Returns the filename (including the extension) of the FilePath.
+
+      extension:
+        - decl: ldtk::FilePath::extension() const -> std::string
+          desc: Returns only the extension of the file (e.g. png, json, txt ...).
+
+structs:
+  - name: Point<T>
+    desc: |
+      Represents a two dimentional coordinate.
+
+      `T` can be one of the following types: `float`, `int` or `unsigned int`.
+
+      Aliases:
+      * `ldtk::FloatPoint` = `ldtk::Point<float>`
+      * `ldtk::IntPoint` = `ldtk::Point<int>`
+      * `ldtk::UIntPoint` = `ldtk::Point<unsigned int>`
+    fields:
+      x:
+        decl: T ldtk::Point<T>::x
+        desc: X coordinate of the Point.
+      y:
+        decl: T ldtk::Point<T>::y
+        desc: Y coordinate of the Point.
+
+  - name: Rect<T>
+    desc: |
+      Represents an axis aligned rectangle.
+
+      `T` can be one of the following types: `float` or `int`.
+
+      Aliases:
+      * `ldtk::FloatRect` = `ldtk::Rect<float>`
+      * `ldtk::IntRect` = `ldtk::Rect<int>`
+    fields:
+      x:
+        decl: T ldtk::Rect<T>::x
+        desc: X coordinate of the top left corner of the Rect.
+      y:
+        decl: T ldtk::Rect<T>::y
+        desc: Y coordinate of the top left corner of the Rect.
+      width:
+        decl: T ldtk::Rect<T>::width
+        desc: Width of the Rect.
+      height:
+        decl: T ldtk::Rect<T>::height
+        desc: Height of the Rect.
+
+  - name: Color
+    desc: Represents a color value in the 32 bits RGBA format.
+    fields:
+      r:
+        decl: std::uint8_t ldtk::Color::r
+        desc: Red component of the Color.
+      g:
+        decl: std::uint8_t ldtk::Color::g
+        desc: Green component of the Color.
+      b:
+        decl: std::uint8_t ldtk::Color::n
+        desc: Blue component of the Color.
+      a:
+        decl: std::uint8_t ldtk::Color::a
+        desc: Alpha component of the Color (opacity).
+
+  - name: EntityRef
+    desc: Represents a reference to an Entity.
+    methods:
+      operator->:
+        - decl: ldtk::EntityRef::operator->() const -> const ldtk::Entity*
+          desc: |
+            Returns a **pointer** to the Entity referenced by the EntityRef.
+
+            This operator allows to access the Entity reference like this:
+
+            ```c++
+            entity_ref->getName(); // returns the name of the referenced Entity
+            ```
+
+  - name: NineSliceBorders
+    desc: Represents the dimensions of the 9-slice tile render.
+    fields:
+      top:
+        decl: int ldtk::NineSliceBorders::top
+        desc: ""
+      right:
+        decl: int ldtk::NineSliceBorders::right
+        desc: ""
+      bottom:
+        decl: int ldtk::NineSliceBorders::bottom
+        desc: ""
+      left:
+        decl: int ldtk::NineSliceBorders::left
+        desc: ""
+
+  - name: IntGridValue
+    desc: Represents the grid values that can be painted on an IntGrid layer.
+    fields:
+      value:
+        decl: const int ldtk::IntGridValue::value
+        desc: ""
+      name:
+        decl: const std::string ldtk::IntGridValue::name
+        desc: ""
+      color:
+        decl: const ldtk::Color ldtk::IntGridValue::color
+        desc: ""
+
+  - name: Vertex
+    desc: |
+      Represents a vertex composed of a position and a texture coordinate.
+
+      The graphic representation of a Tile is composed of 4 vertices.
+    fields:
+      pos:
+        decl: const ldtk::FloatPoint ldtk::Vertex::pos
+        desc: Coordinate of the vertex in pixels, relative to the Level.
+      tex:
+        decl: const ldtk::IntPoint ldtk::Vertex::tex
+        desc: Texture coordinate of the vertex, in pixels.
+
+enums:
+  - name: WorldLayout
+    desc: Contains enum values representing all the possible types of World layouts.
+    values:
+      Free: 0
+      GridVania: 1
+      LinearHorizontal: 2
+      LinearVertical: 3
+
+  - name: LayerType
+    desc: Contains enum values representing all the possible types of Layers.
+    values:
+      IntGrid: 0
+      Entities: 1
+      Tiles: 2
+      AutoLayer: 3
+
+  - name: FieldType
+    desc: |
+      Contains enum values representing all the possible types of a Field.
+
+      These enum values can be used to get a field from an Entity. For example:
+
+      ```c++
+      const auto& field_value = entity.getField<ldtk::FieldType::ArrayEntityRef>();
+      // The type of field_value is ldtk::ArrayField<ldtk::EntityRef>
+      ```
+    values:
+      Int: 0
+      Float: 1
+      Bool: 2
+      String: 3
+      Color: 4
+      Point: 5
+      Enum: 6
+      FilePath: 7
+      EntityRef: 8
+      ArrayInt: 9
+      ArrayFloat: 10
+      ArrayBool: 11
+      ArrayString: 12
+      ArrayColor: 13
+      ArrayPoint: 14
+      ArrayEnum: 15
+      ArrayFilePath: 16
+      ArrayEntityRef: 17
+
+  - name: Dir
+    desc: |
+      Contains enum values representing all the possible Directions of Level neighbours.
+
+      It is used by `ldtk::Level::getNeighbours(const ldtk::Dir&)` and returned by
+      `ldtk::getNeighbourDirection(const Level&)`.
+    values:
+      None: 0
+      North: 1
+      NorthEast: 2
+      East: 3
+      SouthEast: 4
+      South: 5
+      SouthWest: 6
+      West: 7
+      NorthWest: 8
+
+types:
+  - name: FileLoader
+    decl: using ldtk::FileLoader = std::function<std::unique_ptr<std::streambuf>(const std::string&)>
+    desc: |
+      FileLoader is the type of a function that takes the path of a file as parameter and returns a
+      unique pointer to a standard stream buffer for that file.
+
+      This allows to load a Project from a custom source stream (e.g. from a virtual filesystem).

doc/Entity.yml

@@ -0,0 +1,113 @@
+title: Entity
+filename: LDtkLoader/Entity.hpp
+classes:
+  - name: Entity
+    desc: |
+      Represents an Entity instance.
+
+      > [!TIP]
+      > To get the correct sprite data of the Entity as it is shown in the editor,
+      > you should use `hasSprite` to check if the Entity has a sprite,
+      > and then `getTexturePath` and `getTextureRect` to get the texture data.
+
+    fields:
+      layer:
+        decl: const Layer* const layer
+        desc: Pointer to the Layer object that contains the Entity.
+
+      iid:
+        decl: const std::string ldtk::Entity::iid
+        desc: Unique instance ID of the Entity.
+
+    methods:
+      getName:
+        - decl: ldtk::Entity::getName() const -> const std::string&
+          desc: Returns the name of the Entity.
+
+      getSize:
+        - decl: ldtk::Entity::getSize() const -> const ldtk::IntPoint&
+          desc: Returns the size in pixels of the Entity.
+
+      getColor:
+        - decl: ldtk::Entity::getColor() const -> const ldtk::Color&
+          desc: Returns the color of the Entity.
+
+      getPosition:
+        - decl: ldtk::Entity::getPosition() const -> const ldtk::IntPoint&
+          desc: |
+            Returns the position in pixels of the Entity relative to the parent Layer.
+
+            If the layer has an offset different than (0, 0), the layer's total offset should be
+            added to get the position in pixels relative to the parent Level :
+
+            ```c++
+            auto entity_level_pos = entity.getPosition() + entity.layer->getOffset();
+            ```
+
+      getGridPosition:
+        - decl: ldtk::Entity::getGridPosition() const -> const ldtk::IntPoint&
+          desc: Returns the position in grid coordinates of the Entity.
+
+      getGridPosition:
+        - decl: ldtk::Entity::getGridPosition() const -> const ldtk::IntPoint&
+          desc: Returns the computed position in pixels of the Entity relative to the World.
+
+      getPivot:
+        - decl: ldtk::Entity::getPivot() const -> const ldtk::FloatPoint&
+          desc: Returns the pivot of the Entity, a point from (0.f, 0.f) to (1.f, 1.f).
+
+      hasSprite:
+        - decl: ldtk::Entity::hasSprite() const -> bool
+          desc: Returns true if the Entity has a sprite associated to it, returns false otherwise.
+
+      getTexturePath:
+        - decl: ldtk::Entity::getTexturePath() const -> const std::string&
+          desc: Returns the path to the texture of the sprite. Returns an empty string if the Entity has no sprite.
+
+      getTextureRect:
+        - decl: ldtk::Entity::getTextureRect() const -> const ldtk::IntRect&
+          desc: Returns the texture rectangle of this Entity's sprite.
+
+      hasNineSlice:
+        - decl: ldtk::Entity::hasNineSlice() const -> bool
+          desc: Returns true if the Entity's sprite has a 9-slices scaling, returns false otherwise.
+
+      getNineSliceBorders:
+        - decl: ldtk::Entity::getNineSliceBorders() const -> const ldtk::NineSliceBorders&
+          desc: Returns the Entity's 9-slices borders. See NineSliceBorders.
+
+      hasTag:
+        - decl: ldtk::Entity::hasTag(const std::string&) const -> bool
+          desc: Returns `true` if the Entity has the given tag, returns `false` otherwise.
+
+      allTags:
+        - decl: ldtk::Entity::allTags() const -> const std::vector<std::string>&
+          desc: Returns a vector containing all tags of the Entity.
+
+      getField<T>:
+        - decl: |
+            template <typename T>
+            ldtk::Entity::getField<T>(const std::string& name) const -> const ldtk::Field<T>&
+          desc: |
+            Returns the field matching the given name and type. Returned field can be null.
+
+            `T` can either be a `ldtk::FieldType` value, or one of the following types: `int`, `float`,
+            `bool`, `std::string`, `ldtk::Color` , `ldtk::Point`, `ldtk::Enum`, `ldtk::FilePath`.
+
+            For example, if your entity has a field of type color named "hair_color", you can either do :
+
+            ```c++
+            const auto& field = my_entity.getField<ldtk::Color>("hair_color")
+            if (!field.is_null()) {
+                // do something with field.value()
+            }
+            ```
+
+            or
+
+            ```c++
+            const auto& field = my_entity.getField<ldtk::FieldType::Color>("hair_color")
+            if (!field.is_null()) {
+                // do something with field.value()
+            }
+            ```