[Guile-commits] 18/21: Document scm_c_make_port and friends

[Andy Wingo]

wingo pushed a commit to branch wip-port-refactor
in repository guile.

commit 556ac9777b06c0d53713752b1b3ccd6480baf118
Author: Andy Wingo <address@hidden>
Date:   Sat May 14 23:27:38 2016 +0200

    Document scm_c_make_port and friends
    
    * doc/ref/api-io.texi (I/O Extensions): Document scm_c_make_port and
      friends, and document "mode bits".
---
 doc/ref/api-io.texi |   22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 8c91bae..23d3b50 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -2242,7 +2242,9 @@ only you control.  Get a stream from a port using the 
@code{SCM_STREAM}
 macro.  Note that your port methods are only ever called with ports of
 your type.
 
-A port type is created by calling @code{scm_make_port_type}.
+A port type is created by calling @code{scm_make_port_type}.  Once you
+have your port type, you can create ports with @code{scm_c_make_port},
+or @code{scm_c_make_port_with_encoding}.
 
 @deftypefun scm_t_port_type* scm_make_port_type (char *name, size_t (*read) 
(SCM port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM 
src, size_t start, size_t count))
 Define a new port type.  The @var{name}, @var{read} and @var{write}
@@ -2251,6 +2253,24 @@ below.  The other fields are initialized with default 
values and can be
 changed later.
 @end deftypefun
 
address@hidden SCM scm_c_make_port_with_encoding (scm_t_port_type *type, 
unsigned long mode_bits, SCM encoding, SCM conversion_strategy, scm_t_bits 
stream)
address@hidden SCM scm_c_make_port (scm_t_port_type *type, unsigned long 
mode_bits, scm_t_bits stream)
+Make a port with the given @var{type}.  The @var{stream} indicates the
+private data associated with the port, which your port implementation
+may later retrieve with @code{SCM_STREAM}.  The mode bits should include
+one or more of the flags @code{SCM_RDNG} or @code{SCM_WRTNG}, indicating
+that the port is an input and/or an output port, respectively.  The mode
+bits may also include @code{SCM_BUF0} or @code{SCM_BUFLINE}, indicating
+that the port should be unbuffered or line-buffered, respectively.  The
+default is that the port will be block-buffered.  @xref{Buffering}.
+
+As you would imagine, @var{encoding} and @var{conversion_strategy}
+specify the port's initial textual encoding and conversion strategy.
+Both are symbols.  @code{scm_c_make_port} is the same as
address@hidden, except it uses the default port
+encoding and conversion strategy.
address@hidden deftypefun
+
 The port type has a number of associate procedures and properties which
 collectively implement the port's behavior.  Creating a new port type
 mostly involves writing these procedures.