classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Carnë Draug
Hi

I have implemented what I believe to be the first classdef class for
Octave [1]. Kudos to Michael Goffioul for working on it. It seems to
work well for inputParser which opens a whole lot of low-hanging
"classdef" fruits that can now be implemented in Octave. I'll guess we
should start implementing those so we can test classdef.

But one the things that is also needed, is a way to document this
classes? 'help classname' will work fine but only give the first help
text block (constructor?) but what about its other methods? Using
'help class.method' will give nothing. And print_usage() does not yet
work from within methods and how will it? Should we have a giant help
text block at the start or can we somehow start having the help next
to the methods and properties? Matlab seems to create it from
multiple comments through the file, doxygen and javadoc style [2].

Also, we need a consensus for the names used on the @deftypefn
macros when using classdef, as they're not function files anymore.

Carnë

[1] http://hg.savannah.gnu.org/hgweb/octave/rev/ff820f92cbb5
[2] http://www.mathworks.co.uk/help/matlab/matlab_prog/create-help-for-classes.html

Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Richard Crozier
On 21/08/14 15:23, Carnë Draug wrote:

> Hi
>
> I have implemented what I believe to be the first classdef class for
> Octave [1]. Kudos to Michael Goffioul for working on it. It seems to
> work well for inputParser which opens a whole lot of low-hanging
> "classdef" fruits that can now be implemented in Octave. I'll guess we
> should start implementing those so we can test classdef.
>
> But one the things that is also needed, is a way to document this
> classes? 'help classname' will work fine but only give the first help
> text block (constructor?) but what about its other methods? Using
> 'help class.method' will give nothing. And print_usage() does not yet
> work from within methods and how will it? Should we have a giant help
> text block at the start or can we somehow start having the help next
> to the methods and properties? Matlab seems to create it from
> multiple comments through the file, doxygen and javadoc style [2].
>
> Also, we need a consensus for the names used on the @deftypefn
> macros when using classdef, as they're not function files anymore.
>
> Carnë
>
> [1] http://hg.savannah.gnu.org/hgweb/octave/rev/ff820f92cbb5
> [2] http://www.mathworks.co.uk/help/matlab/matlab_prog/create-help-for-classes.html
>
>


I have been testing classdef for a while now, and am also grateful for
all the work that's gone into it. However, with the Octave build I'm,
using, you cannot set a debug break point in a class method. If this
isn't already implemented, I think it would be important to do so
quickly if people are going to start adding classdef classes to Octave core.

Richard

--
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.


Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

PhilipNienhuis
Richard Crozier wrote
On 21/08/14 15:23, Carnë Draug wrote:
> Hi
>
> I have implemented what I believe to be the first classdef class for
> Octave [1]. Kudos to Michael Goffioul for working on it. It seems to
> work well for inputParser which opens a whole lot of low-hanging
> "classdef" fruits that can now be implemented in Octave. I'll guess we
> should start implementing those so we can test classdef.
>
> But one the things that is also needed, is a way to document this
> classes? 'help classname' will work fine but only give the first help
> text block (constructor?) but what about its other methods? Using
> 'help class.method' will give nothing. And print_usage() does not yet
> work from within methods and how will it? Should we have a giant help
> text block at the start or can we somehow start having the help next
> to the methods and properties? Matlab seems to create it from
> multiple comments through the file, doxygen and javadoc style [2].
>
> Also, we need a consensus for the names used on the @deftypefn
> macros when using classdef, as they're not function files anymore.
>
> Carnë
>
> [1] http://hg.savannah.gnu.org/hgweb/octave/rev/ff820f92cbb5
> [2] http://www.mathworks.co.uk/help/matlab/matlab_prog/create-help-for-classes.html
>
>


I have been testing classdef for a while now, and am also grateful for
all the work that's gone into it. However, with the Octave build I'm,
using, you cannot set a debug break point in a class method. If this
isn't already implemented, I think it would be important to do so
quickly if people are going to start adding classdef classes to Octave
What is needed / how difficult would it be to get I/O to .mat files for classdef objects?

Philip
Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

John W. Eaton
Administrator
On 08/22/2014 02:27 AM, PhilipNienhuis wrote:

> What is needed / how difficult would it be to get I/O to .mat files for
> classdef objects?

Do you mean Matlab style .mat files?  What version of them?

I don't know how hard it would be.  Probably similar to what is needed
for the legacy style classes, except that more information must be
stored because classdef classes store more information about the objects
that they represent.

In any case, I think now might be a good time to decide whether we
should continue to support all of the various forms of data files that
load/save handles or deprecate and eventually drop them in favor of only
supporting the MAT style that uses HDF5, possibly with extensions.

The formats we currently support includes Octave text, Octave binary,
Octave HDF5, MATvN.  Dealing with all of them represents a pretty large
maintenance burden for us. I don't count the ascii format here because
that is just for saving numeric data without any header info, and the
old MATv4 format won't change, so very little maintenance is required.
But keeping all of them means that any time we want to add something
like support for classdef objects, we have to update at least four
different formats.  That's a lot of extra work.

Also, I don't think we really support the latest HDF5-based file format
used by Matlab.  So maybe the best thing to do would be to add support
for the latest HDF5-based Matlab format and only add classdef support
for that format.  We could keep the others, but not extend them to
classdef or any other new data types that we add and eventually phase
them out except for reading old data files.

jwe



Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Robert T. Short
In reply to this post by PhilipNienhuis
On 08/21/2014 11:27 PM, PhilipNienhuis wrote:

> Richard Crozier wrote
>> On 21/08/14 15:23, Carnë Draug wrote:
>>> Hi
>>>
>>> I have implemented what I believe to be the first classdef class for
>>> Octave [1]. Kudos to Michael Goffioul for working on it. It seems to
>>> work well for inputParser which opens a whole lot of low-hanging
>>> "classdef" fruits that can now be implemented in Octave. I'll guess we
>>> should start implementing those so we can test classdef.
>>>
>>> But one the things that is also needed, is a way to document this
>>> classes? 'help classname' will work fine but only give the first help
>>> text block (constructor?) but what about its other methods? Using
>>> 'help class.method' will give nothing. And print_usage() does not yet
>>> work from within methods and how will it? Should we have a giant help
>>> text block at the start or can we somehow start having the help next
>>> to the methods and properties? Matlab seems to create it from
>>> multiple comments through the file, doxygen and javadoc style [2].
>>>
>>> Also, we need a consensus for the names used on the @deftypefn
>>> macros when using classdef, as they're not function files anymore.
>>>
>>> Carnë
>>>
>>> [1] http://hg.savannah.gnu.org/hgweb/octave/rev/ff820f92cbb5
>>> [2]
>>> http://www.mathworks.co.uk/help/matlab/matlab_prog/create-help-for-classes.html
>>>
>>>
>>
>> I have been testing classdef for a while now, and am also grateful for
>> all the work that's gone into it. However, with the Octave build I'm,
>> using, you cannot set a debug break point in a class method. If this
>> isn't already implemented, I think it would be important to do so
>> quickly if people are going to start adding classdef classes to Octave
> What is needed / how difficult would it be to get I/O to .mat files for
> classdef objects?
>
> Philip
>
>
>
> --
> View this message in context: http://octave.1599824.n4.nabble.com/classdef-is-pretty-good-now-inputParser-implemented-in-core-What-now-How-to-document-classdef-classe-tp4666168p4666177.html
> Sent from the Octave - Maintainers mailing list archive at Nabble.com.
>
>
>
The question, I think, was how do we self-document classdef classes.  
The same question applies to legacy classes, btw.  I played around with
this for a bit with legacy classes.  texinfo does have mechanisms for
documenting classes, but I didn't see a quick way to incorporate these
constructs into octave.  It seems like some language support will be
required.

Bob


Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Philip Nienhuis
In reply to this post by John W. Eaton
John W. Eaton wrote
On 08/22/2014 02:27 AM, PhilipNienhuis wrote:

> What is needed / how difficult would it be to get I/O to .mat files for
> classdef objects?

Do you mean Matlab style .mat files?  What version of them?
Good counter-question...

I don't know how hard it would be.  Probably similar to what is needed
for the legacy style classes, except that more information must be
stored because classdef classes store more information about the objects
that they represent.

In any case, I think now might be a good time to decide whether we
should continue to support all of the various forms of data files that
load/save handles or deprecate and eventually drop them in favor of only
supporting the MAT style that uses HDF5, possibly with extensions.

The formats we currently support includes Octave text, Octave binary,
Octave HDF5, MATvN.  Dealing with all of them represents a pretty large
maintenance burden for us. I don't count the ascii format here because
that is just for saving numeric data without any header info, and the
old MATv4 format won't change, so very little maintenance is required.
But keeping all of them means that any time we want to add something
like support for classdef objects, we have to update at least four
different formats.  That's a lot of extra work.

Also, I don't think we really support the latest HDF5-based file format
used by Matlab.  So maybe the best thing to do would be to add support
for the latest HDF5-based Matlab format and only add classdef support
for that format.  We could keep the others, but not extend them to
classdef or any other new data types that we add and eventually phase
them out except for reading old data files.
That last suggestion would be the way to go I think.

(OT: I was asking because of a fairly large Matlab-based groundwater modeling "toolbox" (code.google.com/p/mflab) made by a colleague of me that used to work quite well with Octave, save for making movies. I was working on getframe() stuff at that moment, the main missing video package item.
However, some two years ago the complexity of it all grew over my colleague's head and he switched to classdef (and that indeed simplified a lot and opened up lots of new possibilities; much like Carnë described).
I tried a few methods and they seem to work quite well; the big stumbling block however is data I/O to/from .mat files.)

I had a brief look at matio (matio.sf.net) but there's little documentation that matches my limited C++ proficiency. But maybe some stuff from matio can be reused?

Philip
Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Carnë Draug
In reply to this post by Robert T. Short
On 22 August 2014 15:36, Robert T. Short <[hidden email]> wrote:
> The question, I think, was how do we self-document classdef classes.  The
> same question applies to legacy classes, btw.  I played around with this for
> a bit with legacy classes. texinfo does have mechanisms for documenting
> classes, but I didn't see a quick way to incorporate these constructs into
> octave.  It seems like some language support will be required.

Our current documentation system works fine for legacy classes. Each
method is in a separate file which is just a function file, so you can
use exactly the same as you always did. The only thing missing would
be properties but those you can document in the constructor. I think
the only legacy class in Octave core is ftp but "help ftp", "help
ftp/delete", and "help @ftp/delete" all work fine.

Carnë

Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

Philipp Kutin
In reply to this post by Carnë Draug
Hi,

On Thu, Aug 21, 2014 at 4:23 PM, Carnë Draug <[hidden email]> wrote:
> Kudos to Michael Goffioul for working on it.

Thanks indeed to Michael and jwe for making classdef happen. Handle
classes being the only way I know of to create objects that can be
manipulated by reference, it adds the capability to write application
code in a cleanly structured manner known from OO programming.

I have been writing classdef code for a while and have come across the
following differences or missing features relative to MATLAB. I'm
listing them along with workarounds that I have adopted.

* No support for secondary functions.  (I see it's bug #41723.)
Secondary functions are a nice feature to prevent cluttering the
project directory with many small files. As a workaroud, one can use
static methods, but that's slightly imperfect as class names tend to
be LongAndUnwieldy.

* "properties (Constant)" is not implemented.  This would probably
require field initializers to be implemented first. It can be worked
around by using static zero-argument methods instead, since one can
call non-handle functions without parens.

* isa(obj, 'ClassName') checks for exact equality, i.e. for obj being
an instance of class ClassName. MATLAB's isa() also checks for obj
being derived from ClassName, i.e. is equivalent to metaclass(obj) <=
?ClassName

* "methods (Abstract)" is not implemented.  It would require some
tweaking of the parser, I presume. A workaround is to simply have
pseudo-abstract methods in the base class that unconditionally error.

* [objs{:}] when objs is a cell array of same-class objects doesn't
work. I wanted this mainly for writing concise code of looping over
all objects in a cell (I don't keep them in arrays as I find that
concept weird). No big deal.

* I haven't checked, but since my patch wasn't committed I assume that
"calling" a classdef objects still results in an Octave crash. See
patch #8152.

* Classdef files won't be re-read on change. This is very complex of
course. As long as you can just quit a session, start Octave anew, and
restore it, it's not much of an issue.

All in all classdef is pretty usable and I see that in HG, the spammy
debugging messages are now gone, too. Nice!

Cheers,
Philipp

Reply | Threaded
Open this post in threaded view
|

Re: classdef is pretty good now (inputParser implemented in core). What now? How to document classdef classes?

bpabbott
Administrator
On Aug 31, 2014, at 9:28 AM, Philipp Kutin <[hidden email]> wrote:

> * Classdef files won't be re-read on change. This is very complex of
> course. As long as you can just quit a session, start Octave anew, and
> restore it, it's not much of an issue.

What I'm in the habit of doing in Matlab is (1) edit <classdef>, (2) "clear classes", and (3) use <classdef>, where <classdef> is a classdef m-file.

I did a quick test with a very simple classdef object and found this works in Octave as well.

Ben



Reply | Threaded
Open this post in threaded view
|

Matlabs data format as Octaves native format? (was: Re: classdef is pretty good now ...)

Olaf Till-2
In reply to this post by John W. Eaton
On Fri, Aug 22, 2014 at 10:34:31AM -0400, John W. Eaton wrote:

>
> ...
>
> In any case, I think now might be a good time to decide whether we should
> continue to support all of the various forms of data files that load/save
> handles or deprecate and eventually drop them in favor of only supporting
> the MAT style that uses HDF5, possibly with extensions.
>
> The formats we currently support includes Octave text, Octave binary, Octave
> HDF5, MATvN.  Dealing with all of them represents a pretty large maintenance
> burden for us. I don't count the ascii format here because that is just for
> saving numeric data without any header info, and the old MATv4 format won't
> change, so very little maintenance is required. But keeping all of them
> means that any time we want to add something like support for classdef
> objects, we have to update at least four different formats.  That's a lot of
> extra work.
>
> Also, I don't think we really support the latest HDF5-based file format used
> by Matlab.  So maybe the best thing to do would be to add support for the
> latest HDF5-based Matlab format and only add classdef support for that
> format.  We could keep the others, but not extend them to classdef or any
> other new data types that we add and eventually phase them out except for
> reading old data files.
>
> jwe
(Was pointed to this thread by
https://savannah.gnu.org/bugs/index.php?45831 and
https://savannah.gnu.org/bugs/index.php?45833 .)

I'm not familiar with HDF5, but surely, although it's a free framework
format, one would need additional information to support the Matlab
format based on HDF5?

It might be technically easy (I don't know) to get this information
from reading data saved in this format by Matlab, but ... I am not a
lawyer but I remember some speech on video by RMS ... If I understood
it right, there could be the possibility that software companies try
to make it illegal to implement a file format using information from
files output by their software, so possibly there could be the risk to
have to stop using this format some time in the future (?).

If that should indeed be so, it might be a risk to use a Matlab data
format as Octaves native data format, since its use might be forced to
be stopped some time. (Although it could still be reasonable to try to
support the Matlab format as an alternative, as long as there are no
such legal restrictions.)

Again, that's only a thought, I don't know enough about it. But maybe
one should consider contacting the FSF before making a decision about
the data formats supported in the future. (And I got the feeling that
a decision is needed now ...)

Olaf

--
public key id EAFE0591, e.g. on x-hkp://pool.sks-keyservers.net

signature.asc (836 bytes) Download Attachment