Mogre XML commentation tool


17-11-2009 13:13:52

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

More information about you can read on this wiki page.


17-11-2009 15:16:15

New version is up.

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


17-11-2009 16:02:24

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
foreach (String line in logList)
stringBuilder.Append(line + "\n"); // add sorted lines


19-11-2009 07:30:37

Next one.

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


19-11-2009 22:28:16

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).


20-11-2009 00:55:59

What's about the pure .NET classes? ... 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?)


20-11-2009 10:51:58

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.


20-11-2009 20:55:23

Okay, I tried it with MogreNewt, and after fixing nested namespaces, it came up with: ... ects=0&d=1

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


21-11-2009 19:46:03

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.


21-11-2009 21:27:08

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.


22-11-2009 01:53:54

Holy crap, comments for Mogre!

That's awesome smiley80 ! :D


22-11-2009 04:59:12

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.


25-11-2009 13:28:44

Holy crap, comments for Mogre!

That's awesome smiley80 ! :D

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

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 :D


29-11-2009 00:01:06

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


29-11-2009 03:14:26

Nice :D

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.


29-11-2009 14:47:04

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


29-11-2009 15:13:58

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.


29-11-2009 16:28:53

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.


01-12-2009 17:38:59

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


01-12-2009 18:09:39

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


02-12-2009 21:46:33

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.


26-11-2010 20:01:50

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: ... 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.


26-11-2010 20:54:06

Download: ... /Mogre.xml
(Right Click, Save Target As)

Documentation of nested types should work correctly now.


27-11-2010 12:28:44

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.


24-10-2011 15:24:45

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.

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


24-10-2011 17:06:26

Try this one: ... /


24-10-2011 19:36:29

I looked into it by a text editor.

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


24-10-2011 19:58:25

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