Abstract Action#setMask(...) is an internal use-only?

Development
1

Since a lot of you guys are more active here, I would like to take your opinion about documenting the Action#setMask(...).

The situation is:

  • Normally, the AnimLayer is in charge of adjusting the action AnimationMask and this is done periodically on each update.
  • Implementations of the Action class changing the behavior of the Action#setMask(...) method should each override this method and override the documentation if needed, for example: A ClipAction utilized within a BaseAction when the mask propagation flag is off, in this case only a user can call the Action#setMask(...) manually.
  • BaseAction#setMask(...): should also be “Internal use-only” unless wrapped by another BaseAction.

What should be done, in my opinion:

  • Mark the abstract Action#setMask(...) as an internal use-only.
  • Override the Action#setMask(...) for each Action implementation and adjust the documentation according to the internal behavior.

Let me know your opinions.

2

There is another idea which is to mark the Action#setMask(...) as “Internal use-only unless wrapped into a BaseAction”, that is another good option I believe.

3

Most of the “for internal use only” comments have a hidden caveat “unless you know what you are doing”.

So personally, I’m fine with marking them “meant for internal use”. Those doing more advanced things will already be ignoring that.

3 Likes