Request for more and better documentation

[bartley]

Hi,

I have a couple documentation-related requests. I'm using, and thus most interested in, ICE for Java, but I imagine the requests are pretty universally applicable:

1) Copy javadoc-like comments from .ice files to generated Java files. It's really frustrating to not have comments available in the generated Java files and instead have to rely solely on ZeroC's custom documentation format. Some (many?) IDEs (such as IntelliJ IDEA) can parse source files and show comments in a popup within the IDE, so it'd be a huge help to have the comments in there and not have to context-switch all the time.

2) Better documentation overall. For example, the load() method for Properties is described as such:

void load(string file);

Load properties from a file.
Parameters

file

The property file.

Telling me that the argument file is "the property file" is almost totally useless. First, it's really a path to the file, right? What is the form of the path? Must it be absolute? Is it a filesystem path, or a classpath? (btw, if someone can answer these questions, I'd appreciate it! I've tried many different paths, but none seem to work for me. Surely there's a way to package the config file in a jar with the classes and reference it from load(), right? If so, how?)

3) Provide documentation for the Util class. The behavior of many of its methods is not intuitive solely from the method signature. I see Util used all over the place, but have yet to find the documentation for it. Where is it?

Thanks!

[mes]

Hi Chris,

1) Copy javadoc-like comments from .ice files to generated Java files.

That's a reasonable request. We'll consider this for a future release.

First, it's really a path to the file, right? What is the form of the path? Must it be absolute? Is it a filesystem path, or a classpath? (btw, if someone can answer these questions, I'd appreciate it! I've tried many different paths, but none seem to work for me. Surely there's a way to package the config file in a jar with the classes and reference it from load(), right? If so, how?)

Yes, it's a (relative or absolute) filesystem path. I'm afraid it's not possible to load a resource from a JAR file using this operation.

3) Provide documentation for the Util class. The behavior of many of its methods is not intuitive solely from the method signature. I see Util used all over the place, but have yet to find the documentation for it. Where is it?

Most of the methods in Ice.Util involve properties and communicator initialization. See Chapter 28 for more information, and let us know if something isn't clear.

Take care,
- Mark

[bartley]

That's a reasonable request. We'll consider this for a future release.

Awesome, thanks!

Yes, it's a (relative or absolute) filesystem path. I'm afraid it's not possible to load a resource from a JAR file using this operation.

Bummer. I guess it makes since, though, due to the multi-language support requirement. I guess it shouldn't be hard to roll my own support for loading properties, though. I'll try to remember to share it with the group once it's working (is there a preferred place for doing that, or should I just attach it to this thread?)

Most of the methods in Ice.Util involve properties and communicator initialization. See Chapter 28 for more information, and let us know if something isn't clear.

Cool, thanks, I'll check it out.

thanks and best,

chris

[bartley]

Here's the code which helps to create an Ice.Properties instance using a file that's located in a jar (or anywhere else you can get an InputStream):

import java.io.IOException;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.Properties;
import Ice.Util;

/**
 * <p>
 * <code>PropertiesUtil</code> helps create ICE {@link Ice.Properties} instances from {@link Properties}
 * instances.  This is useful for when you want to load ICE properties by some means other than a relative or absolute
 * file path (which is all that {@link Ice.Properties#load(String)} allows), such as from a properties file stored in a
 * jar.
 * </p>
 *
 * @author Chris Bartley (bartley@cmu.edu)
 */
public final class PropertiesUtil
   {
   /**
    * Returns a new {@link Ice.Properties} instance containing all the properties in the given {@link Properties}
    * instance.  If the given {@link Properties} instance is <code>null</code> or empty, this returns an empty
    * {@link Ice.Properties} instance (equivalent to calling {@link Util#createProperties()}).
    */
    public static Ice.Properties createIceProperties(final Properties properties)
      {
      final Ice.Properties iceProperties = Util.createProperties();
      if (properties != null && !properties.isEmpty())
         {
         final Enumeration propertyNames = properties.propertyNames();
         while (propertyNames.hasMoreElements())
            {
            final String key = (String)propertyNames.nextElement();
            final String val = properties.getProperty(key);
            iceProperties.setProperty(key, val);
            }
         }
      return iceProperties;
      }

   private PropertiesUtil()
      {
      // private to prevent instantiation
      }
   }

Example usage:

final Properties javaProperties = new Properties();
javaProperties.load(getClass().getResourceAsStream("/com/foo/bar/config.properties"));
final Ice.Properties iceProperties = PropertiesUtil.createIceProperties(javaProperties);

enjoy!