From 932ab7a97941c16849cccb0a825c286652186ad7 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Wed, 21 Aug 2024 16:25:15 +0200 Subject: [PATCH] Static linking: improve API doc of extensions --- src/extensions/authbasic.mli | 20 ++++++++++++++++---- src/extensions/cors.mli | 16 ++++++++++++++++ src/extensions/deflatemod.mli | 22 ++++++++++++++++++++-- src/extensions/outputfilter.mli | 16 ++++++++++++++++ src/extensions/redirectmod.mli | 18 +++++++++++++++++- src/extensions/revproxy.mli | 18 +++++++++++++++++- src/extensions/rewritemod.mli | 18 +++++++++++++++++- 7 files changed, 119 insertions(+), 9 deletions(-) diff --git a/src/extensions/authbasic.mli b/src/extensions/authbasic.mli index ea1259504..c5da6d69e 100644 --- a/src/extensions/authbasic.mli +++ b/src/extensions/authbasic.mli @@ -18,12 +18,19 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) -val section : Lwt_log_core.section -(** use Lwt_log.Section.set_level in order to debug *) +(** Authbasic: Basic HTTP authentication *) -(** Module [Authbasic]: Basic HTTP Authentication. *) +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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. ++*) -type auth = string -> string -> bool Lwt.t +(** +This module belongs to ocamlfind package + [ocsigenserver.ext.authbasic]. +*) (** This module implements Basic HTTP Authentication as described in {{:http://www.ietf.org/rfc/rfc2617.txt}RFC 2617}. It can be used @@ -37,6 +44,11 @@ type auth = string -> string -> bool Lwt.t very naive one (authentication with a single user/password, given 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 *) + +type auth = string -> string -> bool Lwt.t + val register_basic_authentication_method : (Xml.xml -> auth) -> unit (** This function registers an authentication plugin: it adds a new parser to the list of available authentication schemes. diff --git a/src/extensions/cors.mli b/src/extensions/cors.mli index 239eeb666..c8e18f9be 100644 --- a/src/extensions/cors.mli +++ b/src/extensions/cors.mli @@ -1,3 +1,17 @@ +(** Cross-Origin Resource Sharing *) + +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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]. +*) + val run : ?credentials:bool -> ?max_age:int @@ -5,3 +19,5 @@ val run : -> ?methods:Cohttp.Code.meth list -> unit -> Ocsigen_server.instruction +(** [run] makes it possible to use this extension without + configuration file. *) diff --git a/src/extensions/deflatemod.mli b/src/extensions/deflatemod.mli index 3fc99be6f..638d7e587 100644 --- a/src/extensions/deflatemod.mli +++ b/src/extensions/deflatemod.mli @@ -1,12 +1,30 @@ -val section : Lwt_log_core.section -(** use Lwt_log.Section.set_level in order to debug *) +(** Deflatemod: compress output data *) + +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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.deflatemod]. +*) val set_compress_level : int -> unit val set_buffer_size : int -> unit type filter = [`Type of string option * string option | `Extension of string] +(** Describes the content to deflate, either using its content type, + or file extension *) val run : mode:[`All_but of filter list | `Only of filter list] -> unit -> Ocsigen_server.instruction +(** [run ~mode ()] makes it possible to use this extension without + configuration file. *) + +val section : Lwt_log_core.section +(** Use Lwt_log.Section.set_level in order to change the log level *) diff --git a/src/extensions/outputfilter.mli b/src/extensions/outputfilter.mli index 06551ffad..96bbe27c0 100644 --- a/src/extensions/outputfilter.mli +++ b/src/extensions/outputfilter.mli @@ -1,3 +1,17 @@ +(** 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 <>. ++ 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.outputfilter]. +*) + val run : mode: [ `Rewrite of Ocsigen_header.Name.t * Re.Pcre.regexp * string @@ -5,3 +19,5 @@ val run : | `Code of Cohttp.Code.status ] -> unit -> Ocsigen_server.instruction +(** [run ~mode ()] makes it possible to use this extension without + configuration file. *) diff --git a/src/extensions/redirectmod.mli b/src/extensions/redirectmod.mli index 711f4b1c1..18465ee2b 100644 --- a/src/extensions/redirectmod.mli +++ b/src/extensions/redirectmod.mli @@ -1,5 +1,19 @@ +(** Redirectmod: HTTP redirections *) + +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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]. +*) + val section : Lwt_log_core.section -(** use Lwt_log.Section.set_level in order to debug *) +(** use Lwt_log.Section.set_level in order to set the log level *) type redirection @@ -11,3 +25,5 @@ val create_redirection : -> redirection val run : redirection:redirection -> unit -> Ocsigen_server.instruction +(** [run ~redirection ()] makes it possible to use this extension without + configuration file. *) diff --git a/src/extensions/revproxy.mli b/src/extensions/revproxy.mli index a5c8f842a..607dc9a58 100644 --- a/src/extensions/revproxy.mli +++ b/src/extensions/revproxy.mli @@ -1,5 +1,19 @@ +(** Revproxy: Forward a request to another Web server *) + +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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.revproxy]. +*) + val section : Lwt_log_core.section -(** use Lwt_log.Section.set_level in order to debug *) +(** use Lwt_log.Section.set_level in order to set the log level *) type redirection @@ -12,3 +26,5 @@ val create_redirection : -> redirection val run : redirection:redirection -> unit -> Ocsigen_server.instruction +(** [run ~redirection ()] makes it possible to use this extension without + configuration file. *) diff --git a/src/extensions/rewritemod.mli b/src/extensions/rewritemod.mli index 7b4c52275..1321e60b2 100644 --- a/src/extensions/rewritemod.mli +++ b/src/extensions/rewritemod.mli @@ -1,5 +1,19 @@ +(** Rewrite: Change the request *) + +(** If you want to use this extension with Ocsigen Server's configuration file, ++ have a look at the <>. ++ 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.rewritemod]. +*) + val section : Lwt_log_core.section -(** use Lwt_log.Section.set_level in order to debug *) +(** use Lwt_log.Section.set_level in order to set the log level *) val run : ?continue:bool @@ -8,3 +22,5 @@ val run : -> string -> unit -> Ocsigen_server.instruction +(** [run ~realm ~auth ()] makes it possible to use this extension without + configuration file. *)