Natural Docs Plugin for Unity

This plugin is currently reviewed by the Unity Asset Store review team.

Documenting your code is essential for a good project quality. Even if you are working alone: it just makes sense! With the power of our Natural Docs Plugin for Unity you can document your Unity code like a pro.

What is Natural Docs?

Natural Docs is a free tool written by Greg Valure (gregvalure@naturaldocs.org). You should definitely read the docs on his site and maybe even donate for one of the charities he supports.

Natural Docs is comparable to programs like good ol’ Doxygen – but way cooler!

Just press Run Natural Docs. That’s it!

Why Natural Docs?

The cool thing about Natural Docs is what it’s name supposes: Its comments are designed to be very natural and readable. No weird syntax or tags scattered everywhere.

Let’s a have a look at Microsoft’s standard way of documenting C# code:

/// <summary>
/// Multiplies two integers.
/// </summary>
/// <param name="a">The first integer.</param>
/// <param name="b">The second integer.</param>
/// <returns>
/// The two integers multiplied together.
/// </returns>
/// <example>
/// <code>
/// int c = Muliply(4, 5);
/// if (c > 10)
/// {
///     Console.Log(c);
/// }
/// </code>
/// <seealso cref="Divide(int, int)"/>
void Multiply(int a, int b)
{
}

I really do not like this kind of comments. I don’t want to push my comments through the XML interpreter in my brain first. This is just tedious.

Now the same documentation with Natural Docs:

/* Function: Multiply

   Multiplies two integers.

   Parameters:

      a - The first integer.
      b - The second integer.

   Returns:

      The two integers multiplied together.

   --- Code
   int c = Muliply(4, 5);
   if (c > 10)
   {
      Console.Log(c);
   }
   ---

   See Also:

      <Divide>
*/
void Multiply(int a, int b)
{
}

These examples are more complex ones. Especially for small methods this might be overkill.

But Natural Docs does also understand a short form like this:

// Function: Multiply
// Multiplies two integers and returns the result.
void Multiply(int a, int b)
{
}

Or even a headerless version (C# only)

/**
* Multiplies two integers and returns the result.
*/
void Multiply(int a, int b)
{
}

It doesn’t even matter if you write your comments like this:

/* Function: Multiply
 * ------------------
 * Multiplies two integers and returns the result.
 */

Or like this:

/* +-------------------------------------------------+
   | Function: Multiply                              |
   | Multiplies two integers and returns the result. |
   +-------------------------------------------------+ */

Or this:

//////////////////////////////////////////////////////////////
//
//  Function: Multiply
//  __________________
//
//  Multiplies two integers together and returns the result.
//
//////////////////////////////////////////////////////////////

Natural Docs can handle them. If you want to, you can even mix all these syntax styles in one source file. Even the Microsoft XML or Javadoc syntax can be used.

What does the HTML docs look like?

With the update version 1.1 of the plugin we added a nice new theme that looks like this:

Natural Docs for Unity HTML Output 1
Natural Docs for Unity HTML Output 1
Natural Docs for Unity HTML Output 2
Natural Docs for Unity HTML Output 2

Installing Natural Docs

First thing you have to do is to install Natural Docs on your computer. This works for Windows and MacOS X.

Download Natural Docs on this page.

On Windows just use the installer.

On Mac OS copy the Natural Docs folder from the downloaded ZIP file into your /Application folder.

There is no NaturalDocs.app only a NaturalDocs.exe that we can run on Mac OS with the help of Mono. Since you are a Unity developer and you may use VS Code, chances are high that you have Mono already installed.

Just open a terminal and try this:

mono -V

If an error occurs mono is not installed. If version informations of Mono are printed to the terminal everything is fine and you can install the Natural Docs Unity Plugin if you haven’t already done so.

If you have Brew installed (which I highly recommend) you can use the following to install mono:

brew install mono

Or you can use the Mono download page to download and install.

The last step is to install the Natural Docs Unity Plugin like any other plugin from the Unity Asset Store.

Setup Natural Docs Plugin

After the plugin is installed you have a new option in Unity’s Window menu. Open the plugin window here:

Windows > Documentation with Natural Docs

Now a new window pops up.

You should head over to the Settings/Configuration tab.

We need to tell the Plugin where the NaturalDocs.exe is located on your computer. The plugin checks some common paths for Windows and Mac automatically. But if you installed it in a fancy different location, you should locate the exe-file with the button beside the input text field.

Now add some project informations as you like. A project title is mandatory.

Below the project informations you can select the folder in your project that Natural Docs will scan for scripts. Per default the whole Assets folder is selected. This means that also every installed third party plugin will be documented as well. If you want to document your very own scripts only, you should select your dedicated scripts folder here.

Generating Documentation

Now that everything is setup you can change to the tab Generate Documentation.

The plugins does some checks here under the hood and tells you if something is not setup properly. But if everything is ok, you can now press Run Natural Docs and the documents are generated.

When Natural Docs finishes you can press Browse Documentation to immediately open the index.html file of your brand new docuementation in you web browser. How cool is that!

Links

Leave a Reply

Your email address will not be published. Required fields are marked *