DO NOT REPLY [Bug 21591] New: - WSDL2Java --user documentation unusably unclear

[bu...@apache.org]

DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG 
RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT
<http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21591>.
ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND 
INSERTED IN THE BUG DATABASE.

http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21591

WSDL2Java --user documentation unusably unclear

           Summary: WSDL2Java --user documentation unusably unclear
           Product: Axis
           Version: 1.1
          Platform: All
               URL: http://cvs.apache.org/viewcvs.cgi/~checkout~/xml-
                    axis/java/docs/reference.html#Deployment
        OS/Version: All
            Status: NEW
          Severity: Normal
          Priority: Other
         Component: Documentation
        AssignedTo: axis-dev@ws.apache.org
        ReportedBy: dsb@smart.net


In the Axis Reference Manual, in the section on WSDL2Java, the description
of the --user option is unclear and confusing:

    -U, --user <argument>

    This username is used in resolving the WSDL-URI provided as the input 
    to WSDL2Java.  If the URI contains a username, this will override the 
    command line switch.  ...

First of all, is the argument a username or a URI?  (The wording "this 
username" implies that is it a username, but I don't know of any way that
a username by itself can be used to resolve a URI reference, so maybe the
argument is a URI (with more than just a username).)

Second, _how_ is the argument used to resolve the WSDL URI?  The second
sentence seems to say that if the WSDL URI contains a user name, this 
option's argument won't be used.  But in the other case (the WSDL URI does 
not contain a user name), how would URI resolution add (or otherwise use) 
a username given with the --user option?


The problem seems to be several instances of unclear wording:

- "This username" at the beginning is unclear because the text hasn't 
  referred to any user name yet.  Perhaps "<argument>" should say "<user 
  name>".  Perhaps the text should begin "specifies a user name to use..."

- The second "this" in:

     This username is used ...  If the URI contains a username, this will 
     override... 

  is unclear--is it this command-line option, the given username or the 
  username in the URI?

- The wording "the command line switch" in "...this will override the 
  command line switch" is unclear--does that mean this command line switch
  (--user) or some other one?