Extensions: API doc improvements

doc/indexdoc

@@ -1,5 +1,7 @@
 {1 Ocsigen server - API reference}
-
+{!modules:
+Ocsigen_server
+}
 {2 Extensions}
 {!modules:
 Staticmod
@@ -29,8 +31,8 @@ Ocsigen_config
 {!modules:
 Ocsigen_extensions
 Ocsigen_local_files
+Ocsigen_header
 Ocsigen_stream
-Authbasic
 }
 
 {2 Indexes}

src/extensions/accesscontrol.mli

@@ -32,6 +32,23 @@ This module belongs to ocamlfind package
    [ocsigenserver.ext.accesscontrol].
 *)
 
+(** Example of use (with {% <<a_manual chapter="redirectmod"|Redirectmod>>%}):
+{[
+let _ =
+  Ocsigen_server.start
+    [ Ocsigen_server.host ~regexp:".*"
+        [ Accesscontrol.(
+            if_ (not_ ssl)
+              [ Redirectmod.run
+                  ~redirection:
+                    (Redirectmod.create_redirection ~full_url:false
+                       ~regexp:"(.* )" "https://yourdomain.org/\\1")
+                  () ]
+              [ ... ]) ]
+    ]
+]}
+ *)
+
 type condition
 
 val ip : string -> condition

src/extensions/authbasic.mli

@@ -20,18 +20,30 @@
 
 (** Authbasic: Basic HTTP authentication *)
 
-(** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="authbasic"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
-    counterpart. 
-+*)
+(** If you want to use this extension with Ocsigen Server's configuration file,
+    have a look at the {% <<a_manual chapter="authbasic"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
+    counterpart.
+*)
 
 (**
 This module belongs to ocamlfind package
    [ocsigenserver.ext.authbasic].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*"
+       [ Authbasic.run ~realm:"test"
+            ~auth:(fun u p -> Lwt.return (u = "theuser" && p = "thepassword"))
+            () 
+       ; Staticmod.run ~dir:"static" () ]]
+]}
+ *)
+
 (** This module implements Basic HTTP Authentication as described in
     {{:http://www.ietf.org/rfc/rfc2617.txt}RFC 2617}.  It can be used
     to add an authentication layer to sites with no built-in
@@ -45,7 +57,7 @@ This module belongs to ocamlfind package
     in the configuration file) is provided. *)
 
 val section : Lwt_log_core.section
-(** use Lwt_log.Section.set_level in order to set the log level *)
+(** use [Lwt_log.Section.set_level] in order to set the log level *)
 
 type auth = string -> string -> bool Lwt.t
 

src/extensions/cors.mli

@@ -1,17 +1,37 @@
 (** Cross-Origin Resource Sharing *)
 
 (** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="cors"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
-    counterpart. 
-+*)
+    have a look at the {% <<a_manual chapter="cors"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
+    counterpart.
+*)
 
 (**
 This module belongs to ocamlfind package
    [ocsigenserver.ext.cors].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*"
+       [ Staticmod.run ~dir:"static" ()
+       ; Eliom.run () 
+       ; Cors.run
+          ~max_age:86400
+          ~credentials:true
+          ~methods:[ `POST; `GET; `HEAD ]
+          ~exposed_headers:[ "x-eliom-application"
+                           ; "x-eliom-location"
+                           ; "x-eliom-set-process-cookies"
+                           ; "x-eliom-set-cookie-substitutes" ]
+          () 
+    ]]
+]}
+ *)
+
 val run :
    ?credentials:bool
   -> ?max_age:int

src/extensions/deflatemod.mli

@@ -12,6 +12,25 @@ This module belongs to ocamlfind package
    [ocsigenserver.ext.deflatemod].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*"
+       [ Staticmod.run ~dir:"static" () 
+       ; Deflatemod.run
+           ~mode:(`Only [ `Type (Some "text", Some "html")
+                        ; `Type (Some "text", Some "javascript")
+                        ; `Type (Some "text", Some "css")
+                        ; `Type (Some "application", Some "javascript")
+                        ; `Type (Some "application", Some "x-javascript")
+                        ; `Type (Some "application", Some "xhtml+xml")
+                        ; `Type (Some "image", Some "svg+xml")
+                        ; `Type (Some "application", Some "x-eliom")]) ()
+        ]]
+]}
+ *)
+
 val set_compress_level : int -> unit
 val set_buffer_size : int -> unit
 

src/extensions/extendconfiguration.mli

@@ -1,9 +1,9 @@
 (** Extendconfiguration: More configuration options for Ocsigen Server *)
 
-(** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="extendconfiguration"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
+(** If you want to use this extension with Ocsigen Server's configuration file,
+    have a look at the {% <<a_manual chapter="extendconfiguration"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
     counterpart. 
 +*)
 
@@ -12,6 +12,18 @@ This module belongs to ocamlfind package
    [ocsigenserver.ext.extendconfiguration].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*"
+         [ Extendconfiguration.forbidfile ~extensions:["php"] ()
+         ; Staticmod.run ~dir:"static" ()
+         ]
+     ]
+]}
+ *)
+
 val followsymlinks :
    [`Always | `No | `Owner_match]
   -> Ocsigen_server.instruction

src/extensions/outputfilter.mli

@@ -1,9 +1,9 @@
 (** Outputfilter: Rewrite some part of the output *)
 
-(** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="outputfilter"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
+(** If you want to use this extension with Ocsigen Server's configuration file,
+    have a look at the {% <<a_manual chapter="outputfilter"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
     counterpart. 
 +*)
 
@@ -12,6 +12,8 @@ This module belongs to ocamlfind package
    [ocsigenserver.ext.outputfilter].
 *)
 
+(** See an example of use on the API documentation of {!Revproxy}. *)
+
 val run :
    mode:
      [ `Rewrite of Ocsigen_header.Name.t * string * string

src/extensions/redirectmod.mli

@@ -1,17 +1,34 @@
 (** Redirectmod: HTTP redirections *)
 
-(** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="redirectmod"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
-    counterpart. 
-+*)
+(** If you want to use this extension with Ocsigen Server's configuration file,
+    have a look at the {% <<a_manual chapter="redirectmod"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
+    counterpart.
+*)
 
 (**
 This module belongs to ocamlfind package
    [ocsigenserver.ext.redirectmod].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*"
+       [ Redirectmod.run
+            ~redirection:
+              (Redirectmod.create_redirection
+                ~temporary:false ~full_url:false ~regexp:"^olddir/(.* )$"
+                "https://blahblahblah.org/newdir/\\1")
+              ()
+       ; Staticmod.run ~dir:"static" ()
+       ]
+     ]
+]}
+ *)
+
 val section : Lwt_log_core.section
 (** use Lwt_log.Section.set_level in order to set the log level *)
 

src/extensions/revproxy.mli

@@ -12,14 +12,28 @@ This module belongs to ocamlfind package
    [ocsigenserver.ext.revproxy].
 *)
 
-(** Example of use:
+(** Example of use. Forward all requests to a given directory to the
+same directory of another server running locally on another port.
+We are using it in combination with
+{% <<a_manual chapter="outputfilter"|Outputfilter>>%} to rewrite redirections.
+
 {[
 let _ =
    Ocsigen_server.start
      [ Ocsigen_server.host ~regexp:".*"
-       [ Ocsigen_server.site ["blah"]
-        [ Revproxy.run
-            ~redirection:(Revproxy.create_redirection ) ]]]
+       [ Revproxy.run
+           ~redirection:(Revproxy.create_redirection 
+                           ~full_url:false
+                           ~regexp:"(othersite/.* )"
+                           ~keephost:true
+                           "https://localhost:8123/\\1") 
+           ()
+        ; Outputfilter.run 
+            ~mode:(`Rewrite (Ocsigen_header.Name.location,
+                             "http://localhost:8123/(.* )",
+                             "http://my.publicaddress.org/\\1"))
+            ()
+ ]]
 ]}
  *)
 

src/extensions/rewritemod.mli

@@ -1,9 +1,9 @@
 (** Rewrite: Change the request *)
 
 (** If you want to use this extension with Ocsigen Server's configuration file, 
-+   have a look at the {% <<a_manual chapter="rewritemod"|manual page>>%}.
-+   If you are using Ocsigen Server as a library, use the interface described
-+   here. Each of these functions behaves exactly as its configuration file
+    have a look at the {% <<a_manual chapter="rewritemod"|manual page>>%}.
+    If you are using Ocsigen Server as a library, use the interface described
+    here. Each of these functions behaves exactly as its configuration file
     counterpart. 
 +*)
 

src/extensions/staticmod.mli

@@ -11,6 +11,14 @@
    [ocsigenserver.ext.staticmod].
 *)
 
+(** Example of use:
+{[
+let _ =
+   Ocsigen_server.start
+     [ Ocsigen_server.host ~regexp:".*" [ Staticmod.run ~dir:"static" () ]]
+]}
+ *)
+
 val run :
    ?dir:string
   -> ?regexp:string

src/server/ocsigen_parseconfig.mli

@@ -51,4 +51,9 @@ val first_pass : Xml.xml list -> unit
 *)
 
 val later_pass : Xml.xml list -> unit
+
+(**/**)
+
 val parse_config : ?file:string -> unit -> Xml.xml list list
+(** Returns the config file. Use this if you want to read a config file from
+    your own executable. See {!Ocsigen_server.exec}.*)

src/server/ocsigen_server.mli

@@ -67,21 +67,20 @@ val start :
   -> ?maxretries:int
   -> Ocsigen_extensions.host_config list
   -> unit
-(** Start the server with some instructions. Never returns. 
-
-@param ports The list of HTTP port you want to listen to. The socket type can be 
-used to filter on some IPV4 or IPV6 subnet (default: [[`All, 8080]])
-
-@param ssl_ports The list of HTTPS port you want to listen to.
-
+(** Start the server with some instructions. Never returns.
+    It takes as main parameter a list of virtual hosts (see {!host} below). 
 
+{% Options behave exactly like their <<a_manual chapter="config"|configuration file>>%}
+counterparts.
 *)
 
 type instruction =
   Ocsigen_extensions.virtual_hosts
   -> Ocsigen_extensions.config_info
   -> Ocsigen_lib.Url.path
   -> Ocsigen_extensions.extension
+(** The type of instructions to be used inside an host or site.
+    Instructions are defined by extensions (Staticmod, Eliom, etc.) *)
 
 val host :
    ?regexp:string
@@ -101,9 +100,13 @@ val host :
   -> ?maxuploadfilesize:int64 option
   -> instruction list
   -> Ocsigen_extensions.host_config
+(** You can define one or several virtual hosts corresponding to a given
+    server name or port. *)
 
 val site :
    ?charset:string
   -> Ocsigen_lib.Url.path
   -> instruction list
   -> instruction
+(** Each host may contain some sub-sites corresponding to
+    subdirectories in the URL.*)