Suggested change to MilkToJme documentation

I've been playing with the com.jmex.model.XMLparser.Converters.MilkToJme class and struggling to get it to work. I wasn't using a display context as I was only interested in manipulating the MS3 files and exploring their contents in the resulting Node object. Digging around the code it is now clear that I should use DummyDisplaySystem() in these sorts of situations. Can I therefore ask that this is more clearly stated in the documentation, so this class comment:



/**

  • Started Date: Jun 8, 2004
  • This class converts a .ms3d file to jME's binary format.  The way it converts is by first
  • building the .ms3d scenegraph object, then saving that object to binary format via JmeBinaryWriter

    *
  • @author Jack Lindamood

    */



    is modified to something like this:



    /**
  • Started Date: Jun 8, 2004
  • <p>
  • This class converts a .ms3d file to jME's binary format.  The way it converts
  • is by first building the .ms3d scenegraph object, then saving that object to
  • binary format via {@link com.jmex.model.XMLparser.JmeBinaryWriter}. This
  • class requires a {@link com.jme.system.DisplaySystem} to function correctly.
  • This will normally be provided within a game environment (such as
  • {@link com.jme.app.SimpleGame}). However if you wish to use this in a
  • stand-alone environment, such as part of a tool conversion utility, you
  • should make a call to {@link DummyDisplaySystem} before using this class.
  • <p>
  • The sample below shows such usage. This converts the <code>box.ms3d</code>
  • file to a JME file called <code>box.jme</code>:
  • <pre>
  • String BOX_MS3 = "C:/temp/box.ms3d";
  • String BOX_JME = "C:/temp/box.jme";
  • String fname[] = { BOX_MS3, BOX_JME};

    *
  • // Set up a dummy display system
  • // if one is not available.
  • new DummyDisplaySystem();
  •      
  • // Create jme file.
  • MilkToJme mtj = new MilkToJme();
  • mtj.attemptFileConvert(fname);

    *
  • // JME version now written to box.jme.
  • </pre>

    *
  • @author Jack Lindamood

    */

Except for the code example if have added most of your suggestions. For code examples people should refer to the tests, as those can be checked by compiler and be run to check their proper function while the engine evolves. But you can contribute a test for the standalone conversion if you like…

ok. As I get other bright ideas for updating documentation I'll post them to this forum (keeping code away from the javadoc!).



Ta