patchGNU Octave - Patches: patch #9056, documentation for Java methods and...

 
 

patch #9056: documentation for Java methods and fieldnames

Submitter:  Ernst Reissner <ernstreissner>
Submitted:  Thu 21 Jul 2016 11:57:37 PM UTC
   
 
Category:  Core : other Priority:  5 - Normal
Status:  Done Privacy:  Public
Assigned to:  None Open/Closed:  Closed
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 27 Jul 2016 06:10:54 PM UTC, comment #7: 

To emphasize the fact that the argument is a string representing the name of a class, and not a bare class-name-as-object for example.

Compare with the doc strings for dbclear, imagesc, randi, or typecast.

Mike Miller <mtmiller>
Group Member
Wed 27 Jul 2016 02:11:19 AM UTC, comment #6: 

fieldnames: ok but why is javaclassname in "..."?
same for methods: classname.




Ernst Reissner <ernstreissner>
Tue 26 Jul 2016 05:47:14 PM UTC, comment #5: 

The doc string for fieldnames.m already mentioned struct arguments. The only change you made was to change "When the input is a structure" to "If the input is a structure".

So I think we are both content with fieldnames.m.

I think it's fine to try to unify doc strings to make them more alike, when they actually are. But fieldnames and methods are not really alike, one is primarily meant for struct arguments and one is primarily meant for objects and classes.

The behavior of fieldnames taking a string that is the name of a Java class is, as far as I can tell, an Octave special-case extension. The main purpose of fieldnames is to operate on structs or objects that can be cast to a struct.

I think the right documentation for methods() is to treat Octave objects and Java objects as the same thing, there should be no need to distinguish between an Octave object or a Java object (or a Python object).

Mike Miller <mtmiller>
Group Member
Tue 26 Jul 2016 12:03:28 PM UTC, comment #4: 

Hi again,
it is not true that fieldnames and methods
only return member fields and methods:
also static ones are returned.
I just mixed up parts of the docs of class java.lang.Class,
sorry!!

Ernst Reissner <ernstreissner>
Tue 26 Jul 2016 10:21:19 AM UTC, comment #3: 

Hi Mike,
Well done, but I have still some comments on the comments of fieldnames:
- You missed the description if a struct is given.
- I missed the information that for java
  only the member fields are returned.
The latter may be a bug.
Is there someone with a new version of matlab to try?
Maybe just have a look at 'help fieldnames'.
Try:
octave:1> fieldnames('org.octave.ClassHelper')
ans = {}(0x0)
although scripts/java/org/octave/ClassHelper.java
clearly shows a static field (loader).

Whether bug or not, the behavior shall be documented.

With your version of methods.m i am not content.
If you hava a look at the code,
there are three cases which shall be clearly commented:
- octave-object
- octave-classname
- java-object
- java-classname.

This was done with my comments but not with yours.
Also part of my rewording comes from my intent to unify the two comments.

For methods.m I made the mistake to say that the NAMES of the public methods are returned,
In fact it is the SIGNATURE without access modifier.

I also forgot to comment, that for java only the MEMBER methods are returned.
As for fieldnames, I suppose it is a bug or a deficiency
not to display the static methods.

Ernst Reissner <ernstreissner>
Sat 23 Jul 2016 12:27:03 AM UTC, comment #2: 

Hi Ernst. Thank you for your patch. A lot of the changes you made in this patch are word choice and don't materially improve the documentation (in my opinion). The strings inside of Texinfo @var{} commands should be all lowercase. And when a function can return different numbers of return values, we usually try to declare the common behavior with the inputs first, and then show the difference when one or more output arguments are used.

I tried to carefully extract the spirit of your changes, and came up with these points:

  • Use the name "javaclassname" instead of "jclassname" to be clearer
  • Use the terminology "fields" to refer to data members in Java classes
  • Clarify that methods("classname") can be the name of either an Octave class or a Java class


And I added to that the clarification that methods() can be called with or without a return value for different behavior.

Here is what I pushed to the default branch instead of, but inspired by, your patch:

http://hg.savannah.gnu.org/hgweb/octave/rev/44244c9c177f
http://hg.savannah.gnu.org/hgweb/octave/rev/6c94c7bd55e7

I hope these changes address what you were hoping to accomplish. Please also note the commit message guidelines in Appendix D and at http://wiki.octave.org/Commit_message_guidelines.

Mike Miller <mtmiller>
Group Member
Fri 22 Jul 2016 11:01:21 AM UTC, comment #1: 

(Adapted title)

Thanks Ernst.
I myself have no time for reviewing it now, I hope someone will pick it up soon.

Philip Nienhuis <philipnienhuis>
Group Member
Thu 21 Jul 2016 11:57:37 PM UTC, original submission:  

added documentation.
Now it covers the whole functionality.
Now it is so clear that one realizes,
that methods('ftp') works but not fieldnames('ftp')

Ernst Reissner <ernstreissner>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #37983:  patch22130.txt added by ernstreissner (3KiB - text/plain)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by ernstreissner (Submitted the item)
  • -email is unavailable- added by ernstreissner
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2016-07-23 mtmiller StatusNone Done
        Open/ClosedOpen Closed
    2016-07-22 philipnienhuis CategoryNone Core : other
        Summarymethods and fieldnames documentation for Java methods and fieldnames
    2016-07-21 ernstreissner Attached File- Added patch22130.txt, #37983
        Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code