API Documentation & Help system
Videoblog #4: Click here
You can download the new Release here and take a look at the online API Reference here.
From the first public demonstration to this point, Duality has really made a lot of progress. However, people have been pointing out that the complete lack of documentation isn’t inviting anyone to use it. And they’re correct, so I finally addressed the issue and began writing.
If you’ve previously worked with Visual Studio and C#, you may already know this, but there’s a really useful feature called “Xml comments”. You can equip any Class, Struct or Member with a specifically formatted comment which will then be parsed and compiled into a .xml reference file. The first result you’ll notice are custom documentation popups in Visual Studio, just like the one .Net offers you, but now for your own library. Duality now comes with such .xml file, describing every single Type, Method, Property, Field and Event there is. Using the framework should now be a lot easier to begin with.
But that’s not the only use of an xml documentation file. There is a tool called Sandcastle, which takes your project and documentation files and transforms them into a distinct API reference. Thanks to that, you can now have a look at the Duality API in the online reference – or the offline version, which is included in the Duality download package.
Documenting source code and the framework is one thing, but as developer using Duality, a lot of work is happening in the Duality Editor as well. To support you there, a new help system has been introduced. You’ll notice a new window in the lower right. It’s called advisor and provides information for whatever you’re working on. When hovering a Property in the Object Inspector, the advisor will tell you what it is. The same goes for hovering Resources in the Project View as well as objects in the Scene View. When creating new Resources or Components, it will react to the context menu item you’re hovering. Long story short: The advisor knows what your mouse cursor points at and does its best to provide you with useful information. Hit the F1 key at any time to bring up the API reference regarding the current topic.
The advisors information base mostly comes from the same xml file I talked about earlier. The Duality Editor is now able to parse and use them. That also means: If you start documenting your own game logic or Duality plugin, it will show up in the editor, as soon as you recompile. When working in a team, a programmer can equip the new Components and Properties with his own documentation which will then be available to other team members.