doc: deprecate call-super-method.

* txr.1: Recommend call-super-fun for calling a base class
method. Mark call-super-method deprecated, and add a Note
about why it's not correct to use it for the purpose of
calling a base method.

1 files changed, 16 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index 9a912188..c49180bb 100644
--- a/txr.1
+++ b/txr.1
@@ -23726,7 +23726,7 @@ from
 will call the most derived override of that method.
 
 A derived method can use the
-.code call-super-method
+.code call-super-fun
 to call the corresponding method in the base class.
 
 Thus derived structs can inherit the copy handling logic from base structs, and
@@ -24331,6 +24331,11 @@ from which the slot is inherited.
 .mets (call-super-method < struct-obj < name << argument *)
 .syne
 .desc
+This function is deprecated. Solutions involving
+.code call-super-method
+should be reworked in terms of
+.codn call-super-fun .
+
 The
 .code call-super-method
 retrieves the function stored in the slot
@@ -24354,6 +24359,16 @@ must name a static slot of that structure type.
 The object retrieved from that static slot must be
 callable as a function, and accept the arguments.
 
+Note that it is not correct for a method that is defined
+against a particular type to use
+.code call-super-method
+to call the same method (or any other method) in the supertype
+of that particular type. This is because
+.code call-super-method
+refers to the type of the object instance
+.metn struct-obj ,
+not to the type against which the calling method is defined.
+
 .coNP Function @ call-super-fun
 .synb
 .mets (call-super-fun < type < name << argument *)