Documentation and Code Details
Entry posted by Josh ·
1,956 views
Documentation in Leadwerks 5 will start in the header files, where functions descriptions are being added directly like this:
/// <summary> /// Sets the height of one terrain point. /// </summary> /// <param name="x">Horizontal position of the point to modify.</param> /// <param name="y">Vertical position of the point to modify.</param> /// <param name="height">Height to set, in the range -1.0 to +1.0.</param> virtual void SetHeight(const int x, const int y, const float height);
This will make function descriptions appear automatically in Visual Studio, to help you write code faster and more easily:
Visual Studio can also generate an XML file containing all of the project's function descriptions as part of the build process. The generated XML file will serve as the basis for the online documentation and Visual Studio Code extension for Lua. This is how I see it working:
.png.c7d424b1a30868f5436e27fb69b1f24a.png)
I am also moving all things private to private members. I found a cool trick that allows me to create read-only members. In the example below, you can access the "position" member to get an entity's local position, but you cannot modify it without using the SetPosition() method. This is important because modifying values often involves updating lots of things in the engine under the hood and syncing data with other threads. This also means that any method Visual Studio displays as you are typing is okay to use, and there won't be any undocumented / use-at-your-own risk types of commands like we had in Leadwerks 4.
class Entity { private: Vec3 m_position; public: const Vec3& position; }; Entity::Entity() : position(m_position) {}
It is even possible to make constructors private so that the programmer has to use the correct CreateTerrain() or whatever command, instead of trying to construct a new instance of the class, with unpredictable results. Interestingly, the constructor itself has to be added as a friend function for this to work.
class Terrein { private: Terrain(); public: friend shared_ptr<World> CreateTerrain(shared_ptr<World>, int, int, int) };
The only difference is that inside the CreateTerrain function I have to do this:
auto terrain = shared_ptr<Terrain>(new Terrain);
instead of this, because make_shared() doesn't have access to the Terrain constructor. (If it did, you would be able to create a shared pointer to a new terrain, so we don't want that!)
auto terrain = make_shared<Terrain>();
I have big expectations for Leadwerks 5, so it makes sense to pay a lot of attention to the coding experience you will have while using this. I hope you like it!
-
3
2 Comments
Recommended Comments