From: Stefano Zacchiroli <zack@upsilon.cc>
Date: Mon, 3 Feb 2003 20:49:55 +0000 (+0000)
Subject: added a lot of ocamldoc comments
X-Git-Tag: V_0_0_4_1~67
X-Git-Url: http://matita.cs.unibo.it/gitweb/?a=commitdiff_plain;h=87d44a80101fe624927423b2ab2f1e7586443c07;p=helm.git

added a lot of ocamldoc comments
---

diff --git a/helm/DEVEL/ocaml-http/http_common.mli b/helm/DEVEL/ocaml-http/http_common.mli
index aceeb2842..55e37b073 100644
--- a/helm/DEVEL/ocaml-http/http_common.mli
+++ b/helm/DEVEL/ocaml-http/http_common.mli
@@ -19,32 +19,62 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
-(** Common functionalities *)
+(** Common functionalities shared by other OCaml HTTP modules *)
 
 open Http_types;;
 
   (** whether debugging messages are enabled or not, can be changed at runtime
   *)
 val debug: bool ref
+
   (** print a string on stderr only if debugging is enabled *)
 val debug_print: string -> unit
 
+  (** see {! Http_constants.version} *)
 val http_version: version
+
+  (** see {! Http_constants.server_string} *)
 val server_string: string
 
+  (** pretty print an HTTP version *)
 val string_of_version: version -> string
+
+  (** parse an HTTP version from a string
+  @raise Invalid_HTTP_version if given string doesn't represent a supported HTTP
+  version *)
 val version_of_string: string -> version
 
+  (** pretty print an HTTP method *)
 val string_of_method: meth -> string
+
+  (** parse an HTTP method from a string
+  @raise Invalid_HTTP_method if given string doesn't represent a supported
+  method *)
 val method_of_string: string -> meth
 
+  (** converts an integer HTTP status to the corresponding status value
+  @raise Invalid_code if given integer isn't a valid HTTP status code *)
 val status_of_code: int -> status
+
+  (** converts an HTTP status to the corresponding integer value *)
 val code_of_status: [< status] -> int
 
+  (** @return true on "informational" status codes, false elsewhere *)
 val is_informational: int -> bool
+
+  (** @return true on "success" status codes, false elsewhere *)
 val is_success: int -> bool
+
+  (** @return true on "redirection" status codes, false elsewhere *)
 val is_redirection: int -> bool
+
+  (** @return true on "client error" status codes, false elsewhere *)
 val is_client_error: int -> bool
+
+  (** @return true on "server error" status codes, false elsewhere *)
 val is_server_error: int -> bool
+
+  (** @return true on "client error" and "server error" status code, false
+  elsewhere *)
 val is_error: int -> bool
 
diff --git a/helm/DEVEL/ocaml-http/http_daemon.mli b/helm/DEVEL/ocaml-http/http_daemon.mli
index 7a3ce42d0..784cc8eb9 100644
--- a/helm/DEVEL/ocaml-http/http_daemon.mli
+++ b/helm/DEVEL/ocaml-http/http_daemon.mli
@@ -19,6 +19,11 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** Main OCaml HTTP module.
+    Here you can find two set of functions:
+    - functions which let you start an HTTP Daemon (start* functions)
+    - facility functions which let you sent responses back to clients *)
+
   (** send a CRLF sequence on the given output channel, this is mandatory after
   the last header was sent and before start sending the response body *)
 val send_CRLF: out_channel -> unit
@@ -125,12 +130,25 @@ val start':
   (Http_types.request -> out_channel -> unit) ->
     unit
 
-  (** Trivial static pages HTTP daemon *)
+  (** Object oriented interface to HTTP daemons.
+  @param addr address on which daemon will listen for connections
+  @param port port which daemon will bind
+  see {! Http_types.daemon} *)
+class daemon:
+  ?addr: string -> ?port: int ->
+    unit ->
+      Http_types.daemon
+
+  (** Trivial static pages HTTP daemon.
+  Daemons created using this module will serve directory indexes and files found
+  starting from the working directory *)
 module Trivial :
   sig
+      (** callback function, exposed if you like to use it as a basis to define
+      a more powerful daemon *)
     val callback : string -> 'a -> out_channel -> unit
+
+      (** start the "trivial" HTTP daemon *)
     val start : ?addr:string -> ?port:int -> unit -> unit
   end
 
-class daemon: ?addr: string -> ?port: int -> unit -> Http_types.daemon
-
diff --git a/helm/DEVEL/ocaml-http/http_message.mli b/helm/DEVEL/ocaml-http/http_message.mli
index 9f730939b..eadf50264 100644
--- a/helm/DEVEL/ocaml-http/http_message.mli
+++ b/helm/DEVEL/ocaml-http/http_message.mli
@@ -19,6 +19,8 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** Object Oriented representation of HTTP messages *)
+
 open Http_types;;
 
   (** OO representation of an HTTP message
@@ -29,35 +31,99 @@ class virtual message:
   clisockaddr: Unix.sockaddr -> srvsockaddr: Unix.sockaddr ->
     object
 
+        (** @return message HTTP version, it can be None because older version
+        of the HTTP protocol don't require HTTP version to be told between
+        message source and destination *)
       method version: version option
+
+        (** set message HTTP version *)
       method setVersion: version -> unit
 
+        (** @return message body *)
       method body: string
+
+        (** set message body *)
       method setBody: string -> unit
+
+        (** @return a Buffer.t connected to message body (Warning: changing this
+        buffer will change message body too) *)
       method bodyBuf: Buffer.t
+
+        (** set a new Buffer.t used to keep message body *)
       method setBodyBuf: Buffer.t -> unit
+
+        (** append a string to message body *)
       method addBody: string -> unit
+
+        (** append a whole buffer to message body *)
       method addBodyBuf: Buffer.t -> unit
 
+      (** {i header name comparison are performed in a case-insensitive manner
+      as required by RFC2616, actually the implementation works converting all
+      header names in lowercase} *)
+
+        (** add an HTTP header
+        @param name header's name
+        @param value header's value *)
       method addHeader: name:string -> value:string -> unit
+
+        (** add a list of HTTP headers
+        @param headers a list of pairs: header_name, header_value *)
       method addHeaders: (string * string) list -> unit
+
+        (** like addHeader but replace previous definition of the same header *)
       method replaceHeader: name:string -> value:string -> unit
+
+        (** like addHeaders but replace previous definition of headers that were
+        already defined *)
       method replaceHeaders: (string * string) list -> unit
+
+        (** remove _all_ occurences of an HTTP header from the message
+        @param name name of the header to be removed *)
       method removeHeader: name:string -> unit
+
+        (** @return true if given header exists in message, false otherwise *)
       method hasHeader: name:string -> bool
+
+        (** @return value associated to a given header
+        @param name name of the header to lookup
+        @raise Header_not_found if given header wasn't defined in message *)
       method header: name:string -> string
+
+        (** @return the full set of headers defined for this message, the value
+        returned is an association list from headers name to headers value, an
+        header may occurs more that once in the list *)
       method headers: (string * string) list
 
+
+        (** @return client Unix.sockaddr *)
       method clientSockaddr: Unix.sockaddr
+
+        (** @return client address pretty printed *)
       method clientAddr: string
+
+        (** @return client port *)
       method clientPort: int
 
+        (** @return server Unix.sockaddr *)
       method serverSockaddr: Unix.sockaddr
+
+        (** @return server address pretty printed *)
       method serverAddr: string
+
+        (** @return server port *)
       method serverPort: int
 
+
+        (** @return for requests first request line, for responses first
+        response line.
+        User by derived requests and responses to implement toString method *)
       method private virtual fstLineToString: string
+
+        (** @return a string representation of the message *)
       method toString: string
+
+        (** serialize the message over an output channel *)
       method serialize: out_channel -> unit
 
     end
diff --git a/helm/DEVEL/ocaml-http/http_parser.mli b/helm/DEVEL/ocaml-http/http_parser.mli
index c2c5a7113..e2f9287c8 100644
--- a/helm/DEVEL/ocaml-http/http_parser.mli
+++ b/helm/DEVEL/ocaml-http/http_parser.mli
@@ -19,13 +19,39 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** HTTP messages parsing *)
+
 open Http_types;;
 
+  (** given an HTTP like query string (e.g. "name1=value1&name2=value2&...")
+  @return a list of pairs [("name1", "value1"); ("name2", "value2")]
+  @raise Malformed_query if the string isn't a valid query string
+  @raise Malformed_query_part if some piece of the query isn't valid
+  *)
 val split_query_params: string -> (string * string) list
 
+  (** parse 1st line of an HTTP request
+  @param inchan input channel from which parse request
+  @return a triple meth * url * version, meth is the HTTP method invoked, url is
+  the requested url, version is the HTTP version specified or None if no version
+  was specified
+  @raise Malformed_request if request 1st linst isn't well formed
+  @raise Malformed_request_URI if requested URI isn't well formed *)
 val parse_request_fst_line: in_channel -> meth * Neturl.url * version option
+
+  (** parse HTTP GET parameters from an URL; paramater which were passed with no
+  value (like 'x' in "/foo.cgi?a=10&x=&c=9") are returned associated with the
+  empty ("") string.
+  @return a list of pairs param_name * param_value *)
 val parse_query_get_params: Neturl.url -> (string * string) list
+
+  (** parse the base path (removing query string, fragment, ....) from an URL *)
 val parse_path: Neturl.url -> string
+
+  (** parse HTTP headers. Consumes also trailing CRLF at the end of header list
+  @param inchan input channel from which parse headers
+  @return a list of pairs header_name * header_value
+  @raise Invalid_header if a not well formed header is encountered *)
 val parse_headers: in_channel -> (string * string) list
 
   (** given an input channel, reads from it a GET HTTP request and
diff --git a/helm/DEVEL/ocaml-http/http_parser_sanity.mli b/helm/DEVEL/ocaml-http/http_parser_sanity.mli
index f421c76c7..2603d7da9 100644
--- a/helm/DEVEL/ocaml-http/http_parser_sanity.mli
+++ b/helm/DEVEL/ocaml-http/http_parser_sanity.mli
@@ -19,8 +19,19 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** Sanity test functions related to HTTP message parsing *)
+
+  (** @param name an HTTP header name
+  @raise Invalid_header_name if name isn't a valid HTTP header name *)
 val heal_header_name: string -> unit
+
+  (** @param value an HTTP header value
+  @raise Invalid_header_value if value isn't a valid HTTP header value *)
 val heal_header_value: string -> unit
+
+  (** @param header a pair header_name * header_value
+  @raise Invalid_header_name if name isn't a valid HTTP header name
+  @raise Invalid_header_value if value isn't a valid HTTP header value *)
 val heal_header: string * string -> unit
 
   (** remove heading and/or trailing LWS sequences as per RFC2616 *)
@@ -29,5 +40,7 @@ val normalize_header_value: string -> string
   (** parse an URL from a string.
   @raise Malformed_URL if an invalid URL is encountered *)
 val url_of_string: string -> Neturl.url
+
+  (** pretty print an URL *)
 val string_of_url: Neturl.url -> string
 
diff --git a/helm/DEVEL/ocaml-http/http_request.mli b/helm/DEVEL/ocaml-http/http_request.mli
index ee3494fee..d85ceb278 100644
--- a/helm/DEVEL/ocaml-http/http_request.mli
+++ b/helm/DEVEL/ocaml-http/http_request.mli
@@ -19,6 +19,8 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** Object Oriented representation of HTTP requests *)
+
 open Http_types;;
 
   (** OO representation of an HTTP request
diff --git a/helm/DEVEL/ocaml-http/http_response.mli b/helm/DEVEL/ocaml-http/http_response.mli
index 78ef0fa42..d30f97d40 100644
--- a/helm/DEVEL/ocaml-http/http_response.mli
+++ b/helm/DEVEL/ocaml-http/http_response.mli
@@ -19,8 +19,11 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
+(** Object Oriented representation of HTTP responses *)
+
 open Http_types;;
 
+  (** OO representation of an HTTP response. *)
 class response:
   ?body:string -> ?headers:(string * string) list -> ?version: version ->
   ?clisockaddr: Unix.sockaddr -> ?srvsockaddr: Unix.sockaddr ->
diff --git a/helm/DEVEL/ocaml-http/http_tcp_server.mli b/helm/DEVEL/ocaml-http/http_tcp_server.mli
index b6968254e..d35ad2cf7 100644
--- a/helm/DEVEL/ocaml-http/http_tcp_server.mli
+++ b/helm/DEVEL/ocaml-http/http_tcp_server.mli
@@ -19,16 +19,21 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *)
 
-  (** servers *)
+(** TCP servers used as low-levels for HTTP daemons *)
+
+(** {2 servers} *)
 
   (** single process server *)
 val simple:         Http_types.tcp_server
+
   (** multi threaded server *)
 val thread:         Http_types.tcp_server
+
   (** multi process server *)
 val fork:           Http_types.tcp_server
 
-  (** low level functions *)
+(** {2 low level functions} *)
 
+  (** initialize a passive socket listening on given Unix.sockaddr *)
 val init_socket:    Unix.sockaddr -> Unix.file_descr