private List annotations;

or

private List documentations;

given that it does not really make sense to expose the content of the <xsd:appInfo> elements ?

The content is indeed what I was trying to get.

I would be even better with the "source" information. For instance, I'd like that getDocumentations("version") equals "1.0.0" and getDocumentations("description") equals "Root element of the user configuration file.".
Castor is large, but based on what you've done here, I can provide you the patch that uses a HashMap instead of a Vector to store the documentationList in the Annotation class.

Also, I think the name getDocumentations is not a good idea. That would conflict with a generated class in case where the XSD contains a node named "documentations". I think accessing the attribute directly would be better, or we need to break the Java naming convention (eg get_Documentations). I suppose this could lead to a bug.

The content needs to have backslashes added before the line breaks, otherwise the generated code won't compile.:

_documentations.add("
This is the file specification used to activate a profile. The missing value will be a the location
of a file that needs to exist, and if it doesn't the profile must run. On the other hand exists will test
for the existence of the file and if it is there will run the profile.
");

Finally, how could such a documentation be available for the base-type elements that are transformed into methods? My idea was to use Java annotations, but I've just realized castor wants to be Java-1.3 compatible.

Thanks for all this.

a) Don't worry about the change to a java.util.Map. I will be looking into this right now.
b) I would not worry about this too much, as Castor should - in theory - be able to warn the user about such clashes. I agree that getDocumentations() is not specific enough, but somethinc) g along the lines of getXMLSchemaDocumentations() should be sufficient.
c) Rather than using backslashes for line-breaks, I think 'normalizing' the documentation content should be sufficient. And should be straight-forward to implement.

And finally, not sure what you are referring to with a sentence like ....

> Finally, how could such a documentation be available for the base-type elements that are transformed
> into methods? My idea was to use Java annotations, but I've just realized castor wants to be
> Java-1.3 compatible.

a

Thanks!

b

Yes indeed. A collision is far less probable.

c

Yes, it was my initial idea, too. I eventually changed it to the backslashes idea, because the line breaks could have a meaning.

d

And finally, not sure what you are referring to with a sentence like ....

> Finally, how could such a documentation be available for the base-type elements that are transformed
> into methods? My idea was to use Java annotations, but I've just realized castor wants to be
> Java-1.3 compatible.

Sorry for not being clear once again.
From my initial XSD

<xs:complexType name="Settings">
  <xs:annotation>
    <xs:documentation source="version">1.0.0</xs:documentation>
    <xs:documentation source="description">Root element of the user
    configuration file.</xs:documentation>
  </xs:annotation>
  <xs:all>
    <xs:element name="localRepository" minOccurs="0"
    type="xs:string">
      <xs:annotation>
        <xs:documentation source="version">1.0.0</xs:documentation>
        <xs:documentation source="description">The local
        repository.</xs:documentation>
      </xs:annotation>
    </xs:element>
  </xs:all>
</xs:complexType>

Castor will generate code. This code allows to

Settings settings=new Settings();
settings.setLocalRepository("toto");

Now we can even get documentation for "<settings>"

settings.getXMLSchemaDocumentations("description");

But localRepository is a base-type (xsd:string) and is acceded through methods: getLocalrepository() which returns a String.

How do you get documentation for <localRepository> ?

• The documentation for both <settings> and <localRepository> could be accessible via getAnnotations() (I think) if Castor produces java annotated code like the following

  /* generated class
  */
  @Castor.Annotations.Documentation("description","Root element of the user configuration file")
  public class Settings extends SettingsType implements java.io.Serializable {
  [...]
    @Castor.Annotations.Documentation("descritpion","The local repository")
    public 
  }

• But this is actually not necessary. Another possible is that getXMLSchemaDocumentations() has two parameters : the "source" attribute and the field name, so that

  assertEquals("Root element of the user configuration file.",settings.getXMLSchemaDocumentations("description"));
  assertEquals("The local repository.",settings.getXMLSchemaDocumentations("localRepository","description"));

What do you think? Am I missing an easy way to retrieve the description for localRepository?

How did you implement the backslash idea ?

<xs:documentation source="version">1.0.0</xs:documentation>

should be translated anyhow to the following fragment in the Javadoc for the localRepositrory member:

/**

• Returns the value of field 'localRepository'.
• The field 'localRepository' has the following descriptions:
• @version 1.0.0
• @description tja, was eigentlich
• @return the value of field 'LocalRepository'.
  */
  public java.lang.String getLocalRepository() { return this._localRepository; }

How did you implement the backslash idea ?

Sometimes I just say stupid things (or confuse programming languages)

My implementation is only based on going to the next line. The generated code looks like this:

public Servers() {
        super();
        this._serverList = new java.util.Vector();
        _xmlSchemaDocumentations.put("version", "1.0.0");
        _xmlSchemaDocumentations.put("description", "Configuration of server-specific settings, mainly authentication" +
 +" method. This allows configuration of authentication on a per-server" +
 +" basis." +
 +" ");
    }

I actually wonder whether the following annotation

<xs:documentation source="version">1.0.0</xs:documentation>

should be translated anyhow to the following fragment in the Javadoc for the localRepositrory member:

I don't need it, indeed.

I have no idea whether this could be useful to anyone else.

I'll so some more testing, but I think this can soon be committed to trunk, indeed.

private Map _xmlSchemaDocumentationOfFields = new HashMap();

and allow access to its content by a method as follows:

private String getXmlSchemaDocumentation(String fieldName, String source);

First of all, happy new year, and thanks for this nice piece of software called castor.

To answer your question, yes, having the descritption in a separate class would answer my use case. And it will not increase the size of the main class, which is probably a good thing indeed.

Cheers

Just out of curiosity, what tool is it you are using Castor for ?

http://code.google.com/p/m2settings

My current workaround is based on a 'DocumentationProvider' that parses the XSD (again) to extract the xs:documentation.