Mogre XML commentation tool

This is the discussion thread for the Mogre XML commentation tool of user smiley80.

More information about you can read on this wiki page.

New version is up.

Most types and members should now have comments (events and interfaces are missing).

I extended your code. Now the logfile contains sorted lines.
This makes it more easy to find wanted information (e.g. Member not found).
The code I didn't tested. If there are problems, please tell me.

First, add this at top of Program.cs:
using System.Text.RegularExpressions;

Then search for this line:
File.WriteAllText("MogreXml.log", stringBuilder.ToString());

And above this line add this code:
// arange list alphabetically
List<String> logList = new List<String>(Regex.Split(stringBuilder.ToString(), "\n")); // lines to list
stringBuilder.Remove(0, stringBuilder.Length); // clear
logList.Sort();
foreach (String line in logList)
stringBuilder.Append(line + "\n"); // add sorted lines

Next one.

Everything that can be commented should now have a comment.
And overloaded methods are now handled better.

Would it be possible to use this (or a similar) tool for MogreNewt?
This would be very helpful.

But I don't know if somewhere are usable commentations.
First problem: In MogreNewt are some classes different to OgreNewt
Second problem: MogreNewt is different to the Newton functions

And I don't know if the current library has a documentation. I only found one for Newton 1.x (in internet, not as a file).

What's about the pure .NET classes?
http://www.ogre3d.org/wiki/index.php/MO ... ET_classes

Most of them have a Ogre API description (I linked them on the wiki page).
Maybe we need a workaround to add them to Mogre.xml?
Alternatively we could add them directly to the Mogre code in SVN. (or will there be a conflict with your xml file?)

Would it be possible to use this (or a similar) tool for MogreNewt?
If MogreNewt's header are created manually, I'd recommend adding real XML comments.

What's about the pure .NET classes?

They are commented.

Okay, I tried it with MogreNewt, and after fixing nested namespaces, it came up with:
http://sites.google.com/site/infralicht ... ects=0&d=1

It's in the 'better than nothing' category.

What version of Mogre is the download in the wiki for? This sounds like a great tool, using visual studio to its full potential would be great.

The xml comment file is for 1.6.4. You can use it with older versions, but (depending on API changes) there might be missing or incorrect comments.

But the tool should be able to produce correct comment files for older versions of Mogre.

Holy crap, comments for Mogre!

That's awesome smiley80 !

Just tried it, it's more beautiful than I ever imagined. You don't realize how much you rely on intellisense until you're stuck with out. Smiley80 you deserve a drink for all the things you've done for Mogre.

Holy crap, comments for Mogre!

That's awesome smiley80 !

Yes, that's nice.
But it was only published, because I remind for the commentation problem all 6 months in the forum

Generally many people has good solutions for different problems, but doesn't post it. A general problem for the Ogre community. Great software, much power, but bad documentation (wiki) and many missing or outdated points.
I also talked about this problem in this thread.

By the way ... Bekas - some time ago you said you want to write some important details of you wrapper (and the wrapping process) to the wiki. Do you think you will do it somewhen?
... I'm not shouting - I just want to keep alive your work. And I'm always happy to see you here in the forum

New version is up, which has the hardcoded Mogre stuff removed, i.e. you can use it now for Mogre and MogreNewt.

Usage: MogreXml.exe <AssemblyPath> <NativeNamespace> <ManagedNamespace>
e.g. for Mogre:
MogreXml.exe .\Mogre.dll Ogre Mogre

Nice

I don't know the native namespace for Newton - how do I call this?

Maybe you can add 2 *.bat files to your project - for Mogre and for Newton.

For MogreNewt it's:
MogreXml.exe .\MogreNewt.dll OgreNewt MogreNewt

Why you write .\ in front of the dll file?
It just means the current directory.
Are there problems if you just type the file name (without prefix)?

I wonder that the native namespace of MogreNewt is OgreNewt.
Because it's a port and not a wrapped library.

You can omit ".\". I just wanted to emphasize that you can use a path here.

The native namespace solely depends on which header files you used in Doxygen.
So if you used MogreNewt's headers:
MogreXml.exe .\MogreNewt.dll MogreNewt MogreNewt

But atm it expects Doxygen output from native C++ apps.

smiley80, can your tool additionally create help files in *.chm format?
This would be nice for the Mogre SDK.

No, but Sandcastle and SHFB can create it from the xml file.

Right - I forgot this, even I used it for my own project.
I didn't know that the XML file is the source, but thanks for your hint. I put it to the task list for the SDK.

Hi smiley80,

I recognized, that the description of the enumeration types are not included to the Mogre XML commentation.

For example RenderOperation.OperationTypes
with enum elements like OT_TRIANGLE_LIST

For these enum elements I don't see a description in Visual Studio,
although there are descriptions in the Ogre class reference:
http://www.ogre3d.org/docs/api/html/cla ... 176c19e10d

It would be nice, if you can extend your commentation tool for enums.
If you did so, please offer the new Mogre.xml file here and additionally upload it to the SVN of the MogreSDK. (So it will be included to the next SDK build.)
I'm not shure - maybe you/we also have an SVN for your commentation tool. In this case please upload it there, too.
If your tool isn't inside of an SVN, it would be useful when you add it to an official Mogre repository.

Download:
http://mogresdk.googlecode.com/svn/trun ... /Mogre.xml
(Right Click, Save Target As)

Documentation of nested types should work correctly now.

Fine job (-:

Your whole commentation tool is just great!
I don't want to remember the time when I started with Mogre, because in this time was not even one XML commentation and Mogre development was awful - especially for a beginner.

I found a method whithout Mogre XML description, although there is a description in the online Ogre API reference.

RaySceneQuery.setWorldFragmentType (enum WorldFragmentType wft)

The same problem could be related to:
SceneQuery.setWorldFragmentType (enum WorldFragmentType wft)

Text of both online API descriptions:
Tells the query what kind of world geometry to return from queries; often the full renderable geometry is not what is needed.

@smiley80
Is this description newer than my Mogre.xml file or does your commentation tool ignored this description?

Try this one:
https://sites.google.com/site/infralich ... /Mogre.zip

Thanks.
I looked into it by a text editor.

SceneQuery.SetWorldFragmentType() has a description there.
But RaySceneQuery.SetWorldFragmentType() is not inside the xml file.

There's no need to have both in the xml file. 'RaySceneQuery' is derived from 'SceneQuery', and doesn't override 'SetWorldFragmentType'.