Improve perlclass POD - more information, better synopsis#24503
Conversation
Leont
added
documentation
defer-next-dev
| } | ||
|
|
||
| Just like regular subroutines, methods I<can> be anonymous: | ||
| Just like regular subroutines, methods B<can> be anonymous: |
There was a problem hiding this comment.
I think rather than typeface emphasis like this, it might work better just to reword it a bit:
Just like regular subroutines, methods are permitted to be anonymous:
| hash and populated where possible. | ||
| hash and populated with the found keys according to C<:param> attributes. If | ||
| any C<%arguments> key was not declared as a C<:param> field, an exception is | ||
| raised with a list of surplus key. This means that B<the constructor is |
| In addition, the constructor does not need to be called in the class context | ||
| exclusively. It works just as well to call it on an instance of a class, which | ||
| will automatically create another instance of the same class: |
There was a problem hiding this comment.
Ooof, that might be a slight implementation quirk at the moment. I'm not sure if we want to guarantee exactly that behaviour in the future, and hence whether we should draw attention to it in the docs.
| Same as with bless-based objects, attaching behavior on object destruction is | ||
| done by defining a C<DESTROY> method. See L<perlobj/Destructors> for more | ||
| details. |
There was a problem hiding this comment.
I wouldn't draw attention to this fact currently as I don't think we want to keep that. Longer-term the idea will be to have demolish-style phasers distributed across the (partial) classes. We just haven't implemented that yet as it hasn't turned out to be necessary anywhere.
Adding a DESTROY method has all the complications of SUPER:: chaining and so on, which quickly gets messy.
There was a problem hiding this comment.
We have two conflicting goals here: 1. document how classes work now so people have a reference to work with and 2. document what we wish the finished product should look like.
I think both pieces of information are required, but I believe it is more important to focus on 1. since it's an experimental feature after all. I don't think anyone will be upset that the docs changed together with the implementation as the implementation matured.
That being said, I am happy to mark this information as "this is how you would implement a destructor now, but it is very likely to change" - with better wording, of course. Or maybe a section for destructors in TODO?
There was a problem hiding this comment.
I think any nontrivial amount of effort that goes into it, I'd prefer being directed into making proper destructor phasers actually work properly. Or at least designing them. Or anything that gives forward momentum rather than preserving the status quo.
There was a problem hiding this comment.
Designing the syntax should not be too hard. We already have ADJUST blocks, most logical move would be to create a counterpart that runs just before an object is destroyed. My name suggestions would be TEARDOWN, CLEANUP, or even DEMOLISH like Moose. They should be executed in order of declaration like ADJUST, but for child classes first before parent classes. Global destruction should probably be handled the same way as documented here https://perldoc.perl.org/perlobj#Global-Destruction.
What to do with DESTROY subs - should they lose their special status and not be called on destruction quietly? I think they either need to be honored anyway (ran after TEARDOWN blocks) or we need to raise an error during compilation phase when DESTROY is encountered. To be honest, I can even picture naming the blocks DESTROY and raising an error message like method DESTROY is unsupported while 'class' feature is in effect, use DESTROY block instead when someone tries to name a method DESTROY. This would avoid confusion, and can't see much downside since perlclass classes can't inherit from non-perlclass.
Feel free to ignore all of the above if it is not of any help to you.
jkeenan
removed
the
defer-next-dev
4 participants
This PR adds more information about object lifecycle, expanding this section which wasn't very developed. In addition, synopsis is upgraded to show default field values can be assigned without
ADJUSTblock, and a minor editorial change from italics to bold in a place where we want to stress the word "can".New information in this document was something I was missing when I started adopting perlclass in my project recently, so it should be useful to people who are looking for some specific answers.