NS2Docs

Onos Ate Me

<div class="IPBDescription">Documentation generator</div>Ns2Docs analyzes the lua code for Natural Selection 2 and produces code documentation similar to that of JavaDocs or LuaDoc

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo--><a href="http://ns2docs.bplaced.net/" target="_blank">Generated Docs</a><!--sizec--></span><!--/sizec-->
<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs.zip" target="_blank">Download Ns2Docs</a><!--sizec--></span><!--/sizec-->
<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="https://github.com/DamienHauta/Ns2Docs" target="_blank">GitHub</a><!--sizec--></span><!--/sizec-->

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->System Requirements<!--sizec--></span><!--/sizec-->

<a href="http://www.microsoft.com/en-us/download/details.aspx?id=17851" target="_blank">Microsoft .NET Framework 4</a>

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->Usage<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe [-generator generator name] [-out output path] [source directories]<!--c2--></div><!--ec2-->

If no source directories are supplied, Ns2Docs will try to automatically find the Natural Selection installation directory by searching the registry.

<!--sizeo:5--><span style="font-size:18pt;line-height:100%"><!--/sizeo-->Sample Usage<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -generator Json -out "C:\Natural Selection 2\docs.json" "C:\Program Files (x86)\Steam\steamapps\common\natural selection 2" "c:\My Mod"<!--c2--></div><!--ec2-->
This will parse any files with names ending in .lua that are found in either <i>C:\Program Files (x86)\Steam\steamapps\common\natural selection 2</i> or <i>c:\My Mod</i>. The output will be a Json file that will gets written to <i>C:\Natural Selection 2\docs.json</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Generating Static Html Files<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Changing The Output Folder<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -out "C:\Natural Selection 2\docs"<!--c2--></div><!--ec2-->

The static html files will be written to <i>C:\Natural Selection 2\docs</i> instead of the default <i>ns2docs</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Generating Json Files<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -generator Json<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Changing The Output File<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe -out "C:\Natural Selection 2\docs.json"<!--c2--></div><!--ec2-->

The Json file will be written to <i>C:\Natural Selection 2\docs.json</i> instead of <i>out.json</i>.

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo-->Using Multiple Source Directories<!--sizec--></span><!--/sizec-->

<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Ns2Docs-Console.exe "C:\Program Files (x86)\Steam\steamapps\common\natural selection 2" "c:\My Mod"<!--c2--></div><!--ec2-->

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs.zip" target="_blank">Download Ns2Docs</a><!--sizec--></span><!--/sizec-->

Harimau

Very nice. Just had a look through your website; if you look at Global Variables for instance, at ns2/lua/AlienStructureEffects.lua - the code isn't displaying properly. Could just be my browser though (IE7). Edit: Works fine in firefox. Seems like part of the code is missing though.

player

It works absolutely spiffingly, and indeed produced the most comprehensive overview of NS2's Lua-script to date. This is a keeper.

<!--QuoteBegin-'Harimau'+--><div class='quotetop'>QUOTE ('Harimau')</div><div class='quotemain'><!--QuoteEBegin-->Very nice. Just had a look through your website; if you look at Global Variables for instance, at ns2/lua/AlienStructureEffects.lua - the code isn't displaying properly. Could just be my browser though (IE7). Edit: Works fine in firefox. Seems like part of the code is missing though.<!--QuoteEnd--></div><!--QuoteEEnd-->
It appears to only display a maximum of around 10 lines of the definition, probably to maintain readability of the document. Just follow the "ns2/lua/AlienStructureEffects.lua:#"-link for a complete definition.

McGlaspie

This...is...awesome! Tyvm. Works like a charm.

Viper_two_nine_A

cool! could you add some lua syntax highlighting to the source code viewer?

update: nvm, had js disabled - great program!

KuBaN

I get this error when attempting: <!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->ns2docs.exe: ...Games\Natural Selection 2\ns2docs\lua\leg\parser.lua:182: attempt to call field 'Ca' (a nil value)<!--c2--></div><!--ec2-->

The Demo was a great help and I hope to continue using this invaluable reference, so any advice on this would be appreciated.

☼Lap☼

I get the same error. I can't even find a contact email to email the author.

Onos Ate Me

I fixed the bug and added a more user friendly error messages.
<a href="http://damien.kodingen.com/ns2docs/ns2docs.zip" target="_blank">Download latest version</a>
Turns out the bug was caused by the leg library raising an error while making an error message and class declarations being regarded as Lua keywords preventing code such as <i>local class = {}</i> from being parsed.

<b>Note:</b> In build 184, the file <i>ns2/Build.lua</i> has a syntax error on line 21, <i>buildProgress = "float"</i> needs to end with a comma, preventing Ns2Docs from generating the documentation. Here is the fix for that:
<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->Build.networkVars =
{    
    buildType           = "enum kTechType",
    buildTechId         = "integer",
    buildLocation       = "vector",
    buildOrientation    = "float",
    buildProgress       = "float",
    buildCompleted      = "boolean"
}<!--c2--></div><!--ec2-->

☼Lap☼

Writing doc/classes/index.html
DocVariable.lua:49 attempt t index local 'assignment' (a nil value).

I'm only getting this with files I've modified and not the base NS2. I don't know how to go about finding which variable, or even which file is causing this and why.

Any theories on why or ways I can figure out where the problem is?

Onos Ate Me

<!--quoteo(post=1870358:date=Aug 21 2011, 07:43 AM:name=☼Lap☼)--><div class='quotetop'>QUOTE (☼Lap☼ @ Aug 21 2011, 07:43 AM) <a href="index.php?act=findpost&pid=1870358"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Writing doc/classes/index.html
DocVariable.lua:49 attempt t index local 'assignment' (a nil value).

I'm only getting this with files I've modified and not the base NS2. I don't know how to go about finding which variable, or even which file is causing this and why.

Any theories on why or ways I can figure out where the problem is?<!--QuoteEnd--></div><!--QuoteEEnd-->

It seems that variable assignments are being parsed with no right hand value, I tried to replicate this problem but couldn't. I've updated ns2docs to print the file location and line number of the assignment being parsed when the assignment is <i>nil</i>. This fix will help you pin-point the problem at least.

<a href="http://damien.kodingen.com/ns2docs/ns2docs-3.zip" target="_blank">NSDocs Build 3</a>

☼Lap☼

I think I've seen a trend here. Errors will happen with syntax like this:


S = {}
S.Names= {}
S.Names[0] = {}
S.Names[0]['Name'] = 'Test' <----error line

or similarly

--MessageIndex and MessageIndex[6] are both tables defined in another file....


MessageIndex[6]['energy'] = {Title = 'Energy', Text = 'Your current energy.' }

Something with the way these tables are formed is causing it to come up as nil in your new build

Onos Ate Me

I fixed the assignment bug. NS2Docs will now document <i>S</i> and <i>MessageIndex</i> in the following code:
<!--c1--><div class='codetop'>CODE</div><div class='codemain'><!--ec1-->S = {}
S.Names= {}
S.Names[0] = {}
S.Names[0]['Name'] = 'Test'
MessageIndex = {}
MessageIndex[6]['energy'] = {Title = 'Energy', Text = 'Your current energy.' }<!--c2--></div><!--ec2-->

<a href="http://damien.kodingen.com/ns2docs/ns2docs-4.zip" target="_blank">Download NS2Docs Build 4</a>

☼Lap☼

That fixed everything. No problems anymore. Great program and your response time is amazing.

BJHBnade_spammer

if it works how i think it does this is definitely a nice thing that anyone that wants to make mods should use as correct me if im wrong as i understand it will tell where certain lua commands are defined initially so you can redefine or make sure you get stuff like order of operations as commands are concerned in order to interrupt where they are changed and in order to try and call them before other parts of the script do. so thanks very much Onos Ate Me as im sure this is an invaluable tool to those that dont want to take the time and look through all of the lua files

MurphyIdiot

Very cool! I am going to be using this quite often I suspect :D

Racer1

Would it possible to get this auto-generated for each build and placed on the NS2 website somewhere? - maybe the wiki or even a "Development" page all to itself.

MurphyIdiot

<!--quoteo(post=1872555:date=Sep 1 2011, 09:53 AM:name=Racer1)--><div class='quotetop'>QUOTE (Racer1 @ Sep 1 2011, 09:53 AM) <a href="index.php?act=findpost&pid=1872555"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Would it possible to get this auto-generated for each build and placed on the NS2 website somewhere? - maybe the wiki or even a "Development" page all to itself.<!--QuoteEnd--></div><!--QuoteEEnd-->

Yes, we will try to work something out soon.

rgbDreamer

Could an Admin sticky this? These are clutch to anyone modding NS2.

aeroripper

<!--quoteo--><div class='quotetop'>QUOTE </div><div class='quotemain'><!--quotec-->Could an Admin sticky this? These are clutch to anyone modding NS2.<!--QuoteEnd--></div><!--QuoteEEnd-->

Done.

Onos Ate Me

<!--sizeo:4--><span style="font-size:14pt;line-height:100%"><!--/sizeo--><a href="http://damien.kodingen.com/187/tables/index.html" target="_blank">Ns2Docs Build 5 Preview</a><!--sizec--></span><!--/sizec-->
I've update the docs with the preview of <a href="http://damien.kodingen.com/187/tables/index.html" target="_blank">Ns2Docs build 5</a>. There are lots of changes but the big ones are:
<ul><li> complete interface overhaul to reduce redundancy</li><li> <a href="http://damien.kodingen.com/187/mixins/index.html" target="_blank">mixin support</a></li><li> bugs in displaying variables should be gone</li><li> globals are store in one file instead of across many to increase search-ability</li><li> tables have a bunch of ways to search their data</li></ul>

Works with IE9, Chrome, Firefox, Safari. I haven't checked whether IE 7 or 8 render the pages properly.

<a href="http://damien.kodingen.com/187/tables/Onos/index.html" target="_blank"><img src="http://img6.imageshack.us/img6/8047/nsdy.png" border="0" class="linked-image" /></a>

BJHBnade_spammer

i just noticed Onos has no children! lol

and you sir are a coding ninja.

can i have your babies.
j/k

but seriously what do you actually do for a living? make games? or make software?

Onos Ate Me

Updated the <a href="http://damien.kodingen.com/189/tables/" target="_blank">docs to build 189</a>.

aeroripper

Onos Ate Me you're a 1 man mod making army!

Onos Ate Me

Updated the <a href="http://dl.dropbox.com/u/53107776/ns2docs/190/tables/index.html" target="_blank">docs to build 190</a>

Soul_Rider

<!--quoteo(post=1893775:date=Jan 12 2012, 08:17 AM:name=Onos Ate Me)--><div class='quotetop'>QUOTE (Onos Ate Me @ Jan 12 2012, 08:17 AM) <a href="index.php?act=findpost&pid=1893775"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Updated the <a href="http://dl.dropbox.com/u/53107776/ns2docs/190/tables/index.html" target="_blank">docs to build 190</a><!--QuoteEnd--></div><!--QuoteEEnd-->

Amazing, fantastic and thank you :)

Onos Ate Me

Updated to <a href="http://dl.dropbox.com/u/53107776/ns2docs/193/tables/index.html" target="_blank">build 193</a>
Docs for <a href="http://dl.dropbox.com/u/53107776/ns2docs/electric/1/tables/index.html" target="_blank">Electric Build 1</a>

Harimau

Is there a search function for your live demo?

Onos Ate Me

<!--quoteo(post=1897392:date=Jan 25 2012, 06:32 PM:name=Harimau)--><div class='quotetop'>QUOTE (Harimau @ Jan 25 2012, 06:32 PM) <a href="index.php?act=findpost&pid=1897392"><{POST_SNAPBACK}></a></div><div class='quotemain'><!--quotec-->Is there a search function for your live demo?<!--QuoteEnd--></div><!--QuoteEEnd-->
Tables have a basic search function when javascript is enabled. When I'm unsure where to find the data I'm looking for I'll either use the <i>Find in Files</i> search function in Notepad++ or use <a href="http://dl.dropbox.com/u/53107776/print.lua" target="_blank">this script</a> which will add <i>print</i> to the console commands in NS2. To use the command type <i>print TABLENAME</i> into the console (e.g. <i>print Player</i> to display all the fields for the Player class). Use <i>print TABLENAME FILTER</i> to restrict results (e.g. <i>print Player health</i> to display all fields inside Player with names containing <i>health</i>. <i>print _G</i> will display all the globals currently declared in NS2.

Soul_Rider

Hi Onos,

First off, this is really helpful to me, thanks for all your hardwork.

Secondly, how difficult would it be for you to add the option to output a UML class chart?

If it's a lot of hassle, don't worry, it's just an idea I had as I'm making my own class charts at the moment and it's taking me a while :)

Onos Ate Me

I've updated <a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs%20Build%201.zip" target="_blank">NS2Docs</a> so that it can now output either Json or Html. Also, the source code to is now hosted on <a href="https://github.com/DamienHauta/Ns2Docs.git" target="_blank">GitHub</a>

<a href="http://dl.dropbox.com/u/53107776/ns2docs/Ns2Docs%20Build%201.zip" target="_blank">Download Ns2Docs</a>

Onos Ate Me

<a href="http://dl.dropbox.com/u/53107776/ns2docs/210/tables/index.html" target="_blank">Updated to build 210</a>

<a href="http://dl.dropbox.com/u/53107776/review/210/210vs209.html" target="_blank">Contextual diff with 209</a>
<a href="http://dl.dropbox.com/u/53107776/review/210/210vs208.html" target="_blank">Contextual diff with 208</a>