Original bug ID: 3580
Reporter: administrator
Status: closed
Resolution: fixed
Priority: normal
Severity: minor
Category: ~DO NOT USE (was: OCaml general)

Bug description

Full_Name: Marc Herbert
Version: 3.08.2
OS: linux
Submission from: lns-vlq-37-lyo-82-253-105-246.adsl.proxad.net (82.253.105.246)

This is a suggestion for a small modification of the reference manual,
following an enlightning discussion with Jacques Garrigue.

Most popular OO programming languages that provide a way to enforce
encapsulation provide keywords (like "private" for instance) enforcing
per-class encapsulation. On the other hand, ocaml provides
per-object encapsulation. That is: private methods are restricted
to self and self only: super or even functional updates cannot receive
private methods.

The purpose of this suggestion is not to discuss and compare per-class
vs per-object encapsulation, but only to note that the unfamiliar
per-object encapsulation design of ocaml will probably be missed by a
large number of readers of the reference manual, namely all the
readers who were never exposed to this difference and who will
quickly, wrongly and silently assume that the keyword "private" is
("again") used in ocaml to specify some per-class encapsulation; the
only kind of encapsulation they can think about.

And the vague error message when trying "super#privatemethod" will
probably confuse them even more.

This can probably be avoided by the slight addition at the right
places in the manual of very few sentences underlining this per-object
encapsulation "difference".

Detailed suggestions:

• Section 3.6 "private methods"
  "Private methods are methods that do not appear in object interfaces.
  They can only be invoked from other methods of the same object."
  -->
  "Private methods are methods that do not appear in object interfaces.
  They can only be invoked from other methods of the same object (not
  even from other objects of the same class)."

• Section 6.9.1 "Class types"
  "The flag private indicates whether the method can be accessed from
  outside the class." (this sentence looks almost wrong)
  -->
  "The flag private indicates whether the method can be accessed from
  outside the instantiated object (i.e. whether it appears or not in
  the object type.)"

• Section 6.9.2 "Class expressions"
  "A private method, method private method-name = expr, is a method that
  can only be invoked on self (from other methods of the current class
  as well as of subclasses of the current class).
  -->
  "...can only be invoked on self (from other methods of the current
  class as well as from subclasses' methods)."