Jump to content

Documentation and Code Details

Josh

216 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:

terr.png.b725f0c538e1ec35d9ea764c9d6ccaa4.png

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:

1120020942_UntitledDiagram(1).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!

  • Like 3


2 Comments


Recommended Comments

I am planning to store all code samples on Github here:
https://github.com/Leadwerks/CodeSamples

I am not sure if we will do one sample per command, or just have some more general samples that include a lot of different commands for each subject, or maybe both. I don't know if they will be linked to or shown on the documentation page itself.

Share this comment


Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...