[m-rev.] for review: update io module documentation

[Julien Fischer]

Branches: main, 11.01

Update documentation for the io module.

library/io.m:
 	Don't list the target languages corresponding to the underlying
 	system - the list was out-of-date and the description
 	"underlying system" should be sufficient in any case.

 	Document that the I/O globals field isn't used by anything in
 	the standard library as a whole; not just the io module.

 	Delete an obsolete XXX comment; there is no design flaw w.r.t
 	to the I/O globals and uniqueness since the I/O globals are
 	no longer unique.

Julien.

Index: io.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/library/io.m,v
retrieving revision 1.452
diff -u -r1.452 io.m
--- io.m	4 Jan 2011 05:58:44 -0000	1.452
+++ io.m	11 Jan 2011 07:26:08 -0000
@@ -12,12 +12,11 @@
  %
  % This file encapsulates all the file I/O.
  %
-% We implement a purely logical I/O system using non-logical I/O primitives
-% of the underlying system (C, Java or IL).
-% We ensure referential transparency by passing around a ``state-of-the-world''
-% argument using unique modes. The compiler will check that the state of the
-% world argument is properly single-threaded, and will also ensure that you
-% don't attempt to backtrack over any I/O.
+% We implement a purely logical I/O system using non-logical I/O primitives of
+% the underlying system.  We ensure referential transparency by passing around
+% a ``state-of-the-world'' argument using unique modes. The compiler will check
+% that the state of the world argument is properly single-threaded, and will
+% also ensure that you don't attempt to backtrack over any I/O.
  %
  % Attempting any operation on a stream which has already been closed results
  % in undefined behaviour.
@@ -1202,10 +1201,10 @@
  :- pred io.get_exit_status(int::out, io::di, io::uo) is det.
  :- pred io.set_exit_status(int::in, io::di, io::uo) is det.

-    % The I/O state includes a `globals' field which is not used by the I/O
-    % library, but can be used by the application. The globals field is
-    % of type `univ' so that the application can store any data it wants there.
-    % The following predicates can be used to access this global state.
+    % The I/O state includes a `globals' field which is not used by the
+    % standard library, but can be used by the application. The globals field
+    % is of type `univ' so that the application can store any data it wants
+    % there.  The following predicates can be used to access this global state.
      %
      % Does not modify the I/O state.
      %
@@ -5217,8 +5216,6 @@
  %
  % Global state predicates
  %
-    % XXX design flaw with regard to unique modes
-    % and io.get_globals/3: the `Globals::uo' mode here is a lie.

  io.get_globals(Globals, !IO) :-
      io.lock_globals(!IO),

--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------