Natural Docs Unity Plugin

Create C# Documentation for Unity Like a Pro

Since I’m a Unity developer I do write C# code on a daily basis. While the self written code libraries are growing, the overview is shrinking. This article describes how to use Natural Docs for creating C# documentation.

We all know that proper documentation is a must, but it does not make fun (definitely!) and it is time consuming.

But proper documentation makes you a better developer. Your code gets easier to read, easier to use and easier to maintain. Your whole setup gets more reliable.

In this article I will show you how to install and use the Natural Docs by Greg Valure to create a nice C# documentation based on well formatted HTML pages that can be hosted anywhere or send to anyone.

Then I will show you how to add Natural Docs to Unity editor. So you will be able to generate you C# documentation with the click of a button from within Unity.

Why documenting helps you to create better code

Documenting your code is a crucial process. Nearly as crucial as writing a game concept.

A good documentation helps when re-using your code. You immediately know how to use your methods after not having used your library for a longer time.

I’m sure you all know that situtation: entering your project after a longer break – your are struggeling to “get into the code” again.

You wish you had better documented your code. I know … me too …

If you want other developers to use your code or even work in a team it just does not work without proper documentation.

And often the code documentation is part of a contract.

I really recommend: Start soon! Do it often!

C# documentation

Natural Docs is an automatic documentation system like the famous Doxygen for example.

It scans your project files and creates automatically a nice formatted HTML page with all classes, functions and parameters properly documented.

You have to follow a special C# comment syntax so that Natural Docs is able to recognize all functions and parameters.

First I will show you how to install Natural Docs on your computer.

Installing Natural Docs

Natural Docs is a Mono Application. This means you can also run it on macOS and Linux – if you have Mono installed.

Installing Natural Docs on Windows

  1. Download the Windows version of Natural Docs from it’s website
  2. Then just use the installer. Finished 😉

Installing Natural Docs on macOS

  1. Download the macOS version of Natural Docs from it’s website
  2. Unzip the Archive
  3. Move the Natural Docs folder from the downloaded ZIP file into your /Application folder.

Because of the Mono nature of Natural Docs we need to make sure that Mono is installed and can be executed from terminal.

If you are using VS Code, chances are high, that you have Mono already installed.

Check if Mono is installed

  1. Open a terminal
  2. Enter: mono -V and hit enter

If the terminal prints some version informations you are finished here.

If the terminal prints something like command not found, Mono is not installed. We need to do this first. Therefore I recommend to use Brew, a package manager for macOS. Don’t worry, this takes only one terminal command.

Installing Brew

In the terminal just copy and paste the following command and hit enter.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)

Just watch the terminal doing its job (which can take a little moment) and Brew is installed.

Installing Mono

Maybe you should close and open the terminal again. Just to make sure that the brew command is available.

Now back in terminal copy and paste this:

brew install mono

Wait. Done. Restart the terminal and Mono should be available now. mono -V should print out some version infos.

Add Natural Docs to Unity Editor

If you want to create your docs from within Unity Editor with a single click install our Natural Docs for Unity plugin.

You can read here how to use that plugin. It is quite straight forward. The hardest part, installing Natural Docs, is already done!

Comments Syntax

Now to let Natural Docs understand your C# comments, you have to follow a certain commenting style. But the cool thing about Natural Docs is: it understands a very natural and readable comments syntax.

Here are some examples that will all generate the same result:

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

Natural Docs uses some keywords. In this example Function is a keyword. Only the second example is the headerless syntax. But currently this works with C# only.

Each keyword has a list of variants that can be used as well. So instead of Functions you can also write func, procedure, proc, method etc.

Here is a list of all keywords (in bold) and their variants (below the bold words).

Please also have a look at the Natural Docs Getting started guide and the full Reference. The Getting started guide should give you a good overview to start documenting your code right away.

Conclusion

I hope you were able to install Natural Docs without any hassles. Now go on and have more fun when documenting your code. Nice formatted HTML files will be your reward.

Links

Leave a Reply

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