Documenting copy method for class with overridden copyElement method

I have a handle class with properties whose values include objects of the same class. To make deep copies, I inherit from matlab.mixin.Copyable and override copyElement. It works fine, but I can't see how to document the class properly. The command help myClass.copy shows, of course, the inherited documentation, which is misleading as it says that only a shallow copy will be made. A user would have to be quite sophisticated to know that they also needed to read the documentation for myClass.copyElement to figure out that obj.copy will in fact make a deep copy.

If the designers of matlab.mixin.Copyable foresaw this problem, perhaps there's a solution I'm missing. (Presumably there is a reason they don't let me override copy, which would avoid the issue.) Has anyone any suggestions?

Answer 1

[Aiswarya]

Hi David,

The 'copy' function of matlab.mixin.Copyable takes an array of objects as input, performs 'copyElement' on each object and returns a new array of the same dimensions. It does not recursively copy the handle objects in the property values, unlike deep copy. Infact the default implementation of 'copyElement' also makes shallow copies, but it can be customized to make deep copies as explained in the following documentation: https://www.mathworks.com/help/matlab/matlab_oop/custom-copy-behavior.html#but721f.

The behaviour of deep copy v/s shallow copy is also explained in the following documentation: https://www.mathworks.com/help/matlab/ref/matlab.mixin.copyable-class.html#mw_d0ccde11-6669-4794-8df8-de5b67a591a1

Since the 'copy' function just copies the handles but not the underlying data, it is mentioned that it makes shallow copies. The 'copy' function is meant to provide an interface which subclasses can customize and hence it is a sealed method. However you can add documentation to the 'copyElement' method of your subclass by referring to this documentation: https://www.mathworks.com/help/matlab/matlab_prog/add-help-for-your-program.html

[David Young]

Thank you for your reply, @Aiswarya. However, I do understand how to use Copyable, and I do know how to provide documentation for my copyElement method. Your answer doesn't address my problem, which is that a user sees something misleading if they look at the help for myClass.copy.

Answer 2

[David Young]

There hasn't been an answer, and I think it must be the case that I can't use matlab.mixin.Copyable, because

1. I can change the behaviour of the inherited copy method by overriding copyElement.
2. The copy method is sealed so I can't change what the user sees when they do help myClass.copy.
3. The matlab.mixin.Copyable.copy's documentation does not say that its behaviour might change.

I think this means that matlab.mixin.Copyable is flawed, to the point where it's not really useful.

I'm pretty sure a better design would be to provide a sealed shallowCopy method, and have a copy method which calls it by default and can be overriden. The only thing that would need thinking about is where to handle iteration over arrays.

It turns out, in any case, that it isn't difficult to implement any of this from scratch, so that's my solution and what I've ended up doing. But it's a shame that matlab.mixin.Copyable holds out the promise of a quick way forward, only to spoil it by neglecting the vital detail of how to document a class that inherits from it.