JaxMeXS XSComplexType documentation refers to "element"; more

[Daniel Barclay <da...@fgm.com>]

In the documentation for XSComplexType, several method descriptions
confusingly refer to an element, even though no element is involved:

* getComplexContentType's description says (emphasis added):

     If the _element_ hasn't simple content: Returns the _element_ contents
     type.

   Since getComplexContentType is a method is on XSComplexType, which
   represents a complex type and not an element, shouldn't that documentation
   really say something like the following?:

     If the _type_ doesn't have simple content:  Returns the _type's_
     content type.

There are a number of similar errors:


* isEmpty:

     If the _element_ hasn't simple content: Returns whether the _elements_
     content is empty. ...

     Throws:
         java.lang.IllegalStateException - The _element_ does not have
         complex content

* isMixed:

     If the _element_ hasn't simple content: Returns whether the _elements_
     content is mixed. ...

     Throws:
         java.lang.IllegalStateException - The _element_ does not have
         complex content


* getParticle:

     If the _element_ hasn't simple content: Returns the complex _elements_
     particle.

     Throws:
         java.lang.IllegalStateException - The _element_ has simple content


* isExtension:

     Returns whether the _element_ is a extension of another _element_.


* getExtendedType:

     If the _element_ is an extension: Returns the extended type.

     Throws:
         java.lang.IllegalStateException - The _element_ is no extension.

   (Also, "... is no extension" would be clearer as "... is not an extension"
   (or "... is not an extended type").)


* isRestriction:

     Returns whether the _element_ is a restriction of another _element_.


* getRestrictedType:

     If the _element_ is an restriction: Returns the restricted type.

     Throws:
         java.lang.IllegalStateException - The _element_ is no restriction.

   (And "is no restriction" would be clearer as "is not a restriction"
   (or is not a restricted type).)


Additionally, the lack of needed punctuation makes the documentation
hard to read.  Possessive forms of words almost always need an
apostrophe ("'").  "Elements content" should be "element's content"
(when the meaning is "the content of the element").

Note that where the above documentation says "contents type" (which
should be written "content's type"), it should probably say "content
type" (or "complex type's content type"), since that is the term
used in the XML Schema specification.




Daniel
-- 



---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org

Re: JaxMeXS XSComplexType documentation refers to "element"; more

[robert burrell donkin <rd...@apache.org>]

On Wed, 2005-04-27 at 17:38 -0400, Daniel Barclay wrote:
> Jochen Wiedmann wrote:
> 
> > ...
> 
> > You explain the authors the most with patches. 
> 
> I don't see how that could be true.
> 
> A report that includes the problem text, suggested replacement text,
> an explanation of why the problem text isn't right and why the
> replacement text is right (and maybe reminder that many other parts
> of the documentation have the same problem) contains a lot more
> information that a patch to one file (with only old and new text).

please don't feel that your careful report was in any being denigrated
but appreciate that patches are the lifeblood of any apache project. 

the act of creating a patch means you are contributing to the future of
jaxme by becoming a developer. only developers can grow into committers.
without a healthy community of users, developers and committers, an
apache project must atrophy and die. 

creating a patch demonstrates to the community that you have mastered
the basic skills required to be a jaxme developer. with sustained
contributions over time, you may eventually be elected a committer and
be entitled to cast binding vote's concerning the future of JaxMe. one
day, you might be elected onto the pmc for web services at apache and
help guide the way the whole project progress. it is even possible that
(several years hence) you might even be elected an apache member and so
have an equal stake in the entire apache enterprise.  

but it all starts with a single patch...

> > Besides, note that I
> > won't find the time to integrate your suggestions. 
> 
> Well, yes, you can refuse to fix the problem (and, more importantly,
> refuse to learn how to avoid creating more instances of the same problem);
> I can't stop you.  However, I would hope that you cared enough about the
> usability of JaxMeXS to not refuse.

jochen is a volunteer. he codes jaxme in his own free time. there's no
doubting his commitment. 

there's an tradition here at apache that volunteers must be free to
follow their own fickle star. we all scratch our own itches and decide
our own priorities. we all have jobs which need to be held down and
(surprising as it may seem) other facets to our lives. 

- robert


---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org

Re: JaxMeXS XSComplexType documentation refers to "element"; more

[Jochen Wiedmann <jo...@gmail.com>]

Daniel Barclay wrote:

> Well, yes, you can refuse to fix the problem (and, more importantly,
> refuse to learn how to avoid creating more instances of the same problem);
> I can't stop you.  However, I would hope that you cared enough about the
> usability of JaxMeXS to not refuse.

You've got two serious patches from me within the last two days. These
have been for things, where I knew, that they would be easy to fix for
me, but not for you.

Chaning JavaDocs is something, that you can do at least as good than I
do. So what's wrong if I ask you to create a patch? I am not a paid
consultant or something. I am simply someone without very much time who
tries to concentrate his abilities.

I still offer you to welcome any patches and to integrate them quite
fast. That's more than what you can expect from a lot of other projects.
If you expect more, you're expecting too much from me.


Sorry,

Jochen

---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org

Re: JaxMeXS XSComplexType documentation refers to "element"; more

[Daniel Barclay <da...@fgm.com>]

Jochen Wiedmann wrote:

> ...

> You explain the authors the most with patches. 

I don't see how that could be true.

A report that includes the problem text, suggested replacement text,
an explanation of why the problem text isn't right and why the
replacement text is right (and maybe reminder that many other parts
of the documentation have the same problem) contains a lot more
information that a patch to one file (with only old and new text).

 > Besides, note that I
> won't find the time to integrate your suggestions. 

Well, yes, you can refuse to fix the problem (and, more importantly,
refuse to learn how to avoid creating more instances of the same problem);
I can't stop you.  However, I would hope that you cared enough about the
usability of JaxMeXS to not refuse.

Daniel



---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org

Re: JaxMeXS XSComplexType documentation refers to "element"; more

[Jochen Wiedmann <jo...@gmail.com>]

Daniel Barclay wrote:
> Jochen Wiedmann wrote:
> 
>> Daniel, I totally agree with your points. However, do you think it
>> would require more time to create a patch than writing this mail? :-)
> 
> 
> Definitely.  (Not everyone is already set up for editing and checking in
> JaxMeXS code, and familiar with generating patches and not getting them
> backwards.)
> 
> Besides, if I just patched those instances of the errors, that wouldn't
> do anything to help the authors recognize all the other instances or
> to prevent the creation of additional instances in the future.  (That's
> why I tried to explain the problem and the fix clearly.)

You explain the authors the most with patches. Besides, note that I
won't find the time to integrate your suggestions. I would find the
time, though, to review and integrate patches, because that's a lot faster.


Jochen


---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org

Re: JaxMeXS XSComplexType documentation refers to "element"; more

[Jochen Wiedmann <jo...@gmail.com>]

Daniel, I totally agree with your points. However, do you think it
would require more time to create a patch than writing this mail? :-)

In other words: Patches *quite* welcome.


Jochen

-- 
Outside of a dog, a book is man's best friend.
Inside of a dog, its too dark to read.
(Groucho Marx)

---------------------------------------------------------------------
To unsubscribe, e-mail: jaxme-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: jaxme-dev-help@ws.apache.org