#7 Incorrect Javadoc comment formats

RTK 0.3.3
closed
6
2001-12-18
2001-06-01
No

Hmmm, even the category "Documentaion" in this submit new bug form is a bug... anyway...

I've noticed that in many places (I haven't looked at everything) you are entering @param and
@return info incorrectly.

Incorrect format used:
* @param epp_CheckResult[] array of check results.
* @param String the value for which to search
* @return Boolean the exists boolean in a Boolean object. Will return
* null if the array is null or if the value was not found.

Produces:
Parameters:
epp_CheckResult[] - array of check results.
String - the value for which to search
Returns:
Boolean the exists boolean in a Boolean object. Will return null if the array is null or if the
value was not found.

Correct format should be:
* @param check_results An epp_CheckResult[] array of check results.
* @param check_value The String value for which to search
* @return The exists boolean in a Boolean object. Will return
* null if the array is null or if the value was not found.

Which would produces:
Parameters:
check_results - An epp_CheckResult[] array of check results.
check_value String - The String value for which to search
Returns:
The exists boolean in a Boolean object. Will return null if the array is null or if the value was
not found.

As you can see, the @param should take the parameter name, not its type, as the first arguement,
followed by a description, which may explicitly state the type. @return only has one arguement,
not two, which is the description.

This needs to be corrected throughout. This is important as in methods such as addXMLElement()
in EPPXMLBase their are multiple String parameters, so the parameter descriptions could be
confusing. One should not have to count their order in the list to discern which parameter is being
described (hence why the parameter name should be used instead).

Discussion

  • Daniel Kirkdorffer

    • priority: 5 --> 6
     
  • Daniel Manley

    Daniel Manley - 2001-06-13
    • assigned_to: nobody --> olegs
     
  • Daniel Manley

    Daniel Manley - 2001-09-04
    • assigned_to: olegs --> tubadanm
     
  • Anthony Eden

    Anthony Eden - 2001-09-04

    Logged In: YES
    user_id=75589

    The lack of documentation in the epp_xxx classes is what
    bothers me. These are the classes that I tend to deal with
    on a regular basis (for example working with
    epp_DomainInfoRsp after issuing an epp_DomainInfoReq) and
    yet there is no documentation on these classes. I had to
    go to the EPP User's Guide to find out the difference
    between the hosts and nameServers fields whereas I would
    have preferred to be able to determine this by looking at
    the JavaDoc documentation for epp_DominInfoRsp.

     
  • Daniel Manley

    Daniel Manley - 2001-10-09

    Logged In: YES
    user_id=211976

    ok, we've started working on this, mostly in 0.4.0. It's a
    long job so it may take a little while. Bear with us please.

    Thanks,
    Dan

     
  • Daniel Manley

    Daniel Manley - 2001-12-18

    Logged In: YES
    user_id=211976

    with the release of 0.4.1, we've added the first draft of
    javadocs for the epp_* classes. I'll close this bug. If
    there are any further problems with javadocs (wording,
    spelling, grammar, lacking details, etc...), open a new bug
    specific to your problems. Thanks.

     
  • Daniel Manley

    Daniel Manley - 2001-12-18
    • status: open --> closed
     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks