DOC: convert library(pio) documentation to DocLog format

diff --git a/src/lib/pio.pl b/src/lib/pio.pl
index 42f641db9abb177cc08046ef09c9865cf75f257d..fdc5bcb1e75d58afec99705b2dd49f9cdeb685a3 100644 (file)
--- a/src/lib/pio.pl
+++ b/src/lib/pio.pl
@@ -1,13 +1,11 @@
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   Pure I/O
-   ========
+/** Pure I/O.
 
    Our goal is to encourage the use of definite clause grammars (DCGs)
-   for describing strings. The predicates phrase_from_file/[2,3],
-   phrase_to_file/[2,3] and phrase_to_stream/2 let us apply DCGs
+   for describing strings. The predicates `phrase_from_file/[2,3]`,
+   `phrase_to_file/[2,3]` and `phrase_to_stream/2` let us apply DCGs
    transparently to files and streams, and therefore decouple side-effects
    from declarative descriptions.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+*/
 
 :- module(pio, [phrase_from_file/2,
                 phrase_from_file/3,
@@ -29,16 +27,18 @@
 :- meta_predicate(phrase_to_file(2, ?, ?)).
 :- meta_predicate(phrase_to_stream(2, ?)).
 
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   phrase_from_file(GRBody, File)
-
-   True if grammar rule body GRBody covers the contents of File,
-   represented as a list of characters.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+%% phrase_from_file(+GRBody, +File)
+%
+%  True if grammar rule body GRBody covers the contents of File,
+%  represented as a list of characters.
 
 phrase_from_file(NT, File) :-
     phrase_from_file(NT, File, []).
 
+%% phrase_from_file(+GRBody, +File, +Options)
+%
+%  Like `phrase_from_file/2`, using Options to open the file.
+
 phrase_from_file(NT, File, Options) :-
     (   var(File) -> instantiation_error(phrase_from_file/3)
     ;   must_be(list, Options),
@@ -68,23 +68,22 @@ reader_step(Stream, Pos, Xs0) :-
             stream_to_lazy_list(Stream, Xs)
         ).
 
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   phrase_to_stream(+GRBody, +Stream)
-
-   Emit the list of characters described by the grammar rule body
-   GRBody to Stream.
-
-   An ideal implementation of phrase_to_stream/2 writes each character
-   as soon as it becomes known and no choice-points remain, and thus
-   avoids the manifestation of the entire string in memory. See #691
-   for more information.
-
-   The current preliminary implementation is provided so that Prolog
-   programmers can already get used to describing output with DCGs,
-   and then writing it to a file when necessary. This simple
-   implementation suffices as long as the entire contents can be
-   represented in memory, and thus covers a large number of use cases.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+%% phrase_to_stream(+GRBody, +Stream)
+%
+%  Emit the list of characters described by the grammar rule body
+%  GRBody to Stream.
+%
+%  An ideal implementation of `phrase_to_stream/2` writes each
+%  character as soon as it becomes known and no choice-points remain,
+%  and thus avoids the manifestation of the entire string in memory.
+%  See [#691](https://github.com/mthom/scryer-prolog/issues/691) for
+%  more information.
+%
+%  The current preliminary implementation is provided so that Prolog
+%  programmers can already get used to describing output with DCGs,
+%  and then writing it to a file when necessary. This simple
+%  implementation suffices as long as the entire contents can be
+%  represented in memory, and thus covers a large number of use cases.
 
 phrase_to_stream(GRBody, Stream) :-
         phrase(GRBody, Cs),
@@ -101,14 +100,18 @@ phrase_to_stream(GRBody, Stream) :-
         % maplist(put_char(Stream), Cs). It also works for binary streams.
         '$put_chars'(Stream, Cs).
 
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   phrase_to_file(+GRBody, +File), writing the string described
-   by GRBody to File.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+%% phrase_to_file(+GRBody, +File)
+%
+%  Write the string described by GRBody to File.
 
 phrase_to_file(GRBody, File) :-
         phrase_to_file(GRBody, File, []).
 
+
+%% phrase_to_file(+GRBody, +File, +Options)
+%
+%  Like `phrase_to_file/2`, using Options to open the file.
+
 phrase_to_file(GRBody, File, Options) :-
         setup_call_cleanup(open(File, write, Stream, Options),
                            phrase_to_stream(GRBody, Stream),