Jade Documentation
One of the things the engine lacked since the start of the project was
a good documentation: inside the code and an outside reference.
The
first problem was because the code was a heavy mix of english and
spanish, and a lot of things were unexplained. While the engine has
being fully translated to english, some things remain undocumented
(with a nice TODO tag to remember myself that I have to fix that
someday). That problem will be fixed as the engine moves on.
The
second problem was an outside reference for the engine. Usually, .NET
projects use NDoc to build their help, but due to several reasons
(mostly lack of support from the .NET community), the NDoc project
died. The engine uses generics and it has some references to unmanaged
assemblies, 2 things NDoc dislikes a lot, so it wasn´t possible to
build our documentation with it.
Other tools on the web are professional documenters that cost at least 400-500 dollars, and well, I´m not going to pay that.
But
this kind of documentation is quite needed for the community (it is one
of the things people asked about first). gonzo helped building a
documentation file with an alpha version of NDoc 2.0 and taking out the
references to Vorbisdotnet.dll. I continued searching for something (a
lot of people have this same problem, so there must be a solution). So
after browsing a lot, I discovered project "Sandcastle":
Microsoft Sandcastle BlogThis
project are the tools Microsoft uses to build its own documentation. I
was quite happy when I found this: "now I can build the doc for Jade!"
I though. But another problem arised: using Sandcastle CTP was far from
"intuitive" or "easy". But by chance (reading the CodeProject
Newsletter), I found this jewel from Ashley van Gerven:
Sandcastle CHM-compile BAT script & configuration utilityThis
project builds a .bat script that calls Sandcastle and HTML Workshop to
build a nice .chm file with the documentation of your assembly. After
some tries, I managed to create 2 .chm, one for Jade and one for
Jade.AI, and the results are impressive in my opinion. The files are
now uploaded in the 1.0.0.0 Release (Jad 1.0 Documentation), so have a
look at them, you won´t be disappointed.
After a long fight, it seems Jade has got a nice documentation (at last!).