Permalink
Browse files

Add documentation.

  • Loading branch information...
1 parent a062eb9 commit 35b45b66d914ed73ba69ad55fe7658b2cbe66fff @andrenth committed Sep 14, 2012
Showing with 92 additions and 6 deletions.
  1. +8 −1 _oasis
  2. +51 −0 lib/SRS.mli
  3. +33 −5 setup.ml
View
9 _oasis
@@ -8,11 +8,18 @@ License: BSD3
BuildTools: ocamlbuild
Plugins: META (0.3)
-Library srs
+Library "srs"
Path: lib
CompiledObject: best
Modules: SRS
CSources: srs_stubs.c
CCLib: -lsrs2
CCOpt: -Wall -Werror
XMETADescription: OCaml SRS library
+
+Document "srs"
+ Title: SRS documentation
+ Type: ocamlbuild (0.3)
+ BuildTools+: ocamldoc
+ XOCamlbuildPath: lib
+ XOCamlbuildLibraries: srs
View
@@ -1,22 +1,73 @@
+(** OCaml bindings to {{:http://www.libsrs2.org/} libsrs2}. *)
+
type t
+ (** The type of an SRS instance. *)
exception SRS_error of string
+ (** The exception raised by SRS functions in case of errors. *)
val create : unit -> t
+ (** Creates a new SRS instance using [=] as the SRS separator, [21] as the
+ SRS address validity period, [4] as the SRS hash length and hash
+ minimum length. *)
+
val add_secret : t -> string -> unit
+ (** Adds a new secret to an SRS instance. Only the secret used in the
+ first call to [add_secret] is used for forward-rewriting addresses.
+ All secrets are attempted for reverse-rewriting addresses. Must be
+ called at least once. *)
+
val forward : t -> string -> string -> string
+ (** [forward srs sender fwd] rewrites [sender] to look like an address
+ from domain [fwd] using the information from SRS instance [srs]. *)
+
val reverse : t -> string -> string
+ (** [reverse srs sender] rewrites an SRS-rewritten address [sender] back
+ into its original form using the information from SRS instance [srs]. *)
+
val set_separator : t -> char -> unit
+ (** Sets the character used as the initial SRS separator, that is, the one
+ immediately after the [SRS0] or [SRS1] tags. Valid separators are [=],
+ [+] and [-]. *)
+
val get_separator : t -> char
+ (** Gets the character used as the initial SRS separator. *)
+
val set_max_age : t -> int -> unit
+ (** Sets the amount of time (in days) during which SRS-rewritten addresses
+ are valid. *)
+
val get_max_age : t -> int
+ (** Gets the maximum SRS address age. *)
+
val set_hash_length : t -> int -> unit
+ (** Sets the length of the hash part of SRS-rewritten addresses. *)
+
val get_hash_length : t -> int
+ (** Gets the length of the hash part of SRS-rewritten addresses. *)
+
val set_hash_min : t -> int -> unit
+ (** Sets the minimum length of an SRS hash. *)
+
val get_hash_min : t -> int
+ (** Gets the minimum length of an SRS hash. *)
+
val set_no_forward : t -> bool -> unit
+ (** If set to true, the SRS instance will not perform forward rewritting. *)
+
val get_no_forward : t -> bool
+ (** Gets the value set by {!set_no_forward}. *)
+
val set_no_reverse : t -> bool -> unit
+ (** If set to true, the SRS instance will not perform reverse rewritting. *)
+
val get_no_reverse : t -> bool
+ (** Gets the value set by {!set_no_reverse}. *)
val make : string * string list -> int -> int -> char -> t
+ (** Helper function to create and initialize an SRS instance in one step.
+ [make (secret, secrets) max_age hash_len sep] will create an SRS
+ instance using [secret] as the initial secret and [secrets] as additional
+ secrets. The address validity duration will be set to [max_age], the
+ SRS hash length will be set to [hash_len] and the SRS separator will be
+ set to [sep]. *)
View
@@ -1,7 +1,7 @@
(* setup.ml generated for the first time by OASIS v0.3.0 *)
(* OASIS_START *)
-(* DO NOT EDIT (digest: 832ecbed041effa78058b50e42171a66) *)
+(* DO NOT EDIT (digest: 0876b5549c8d2376ae7132da0b794d69) *)
(*
Regenerated by OASIS v0.3.0
Visit http://oasis.forge.ocamlcore.org for more information and
@@ -5563,12 +5563,12 @@ let setup_t =
BaseSetup.configure = InternalConfigurePlugin.configure;
build = OCamlbuildPlugin.build;
test = [];
- doc = [];
+ doc = [("srs", OCamlbuildDocPlugin.doc_build "lib")];
install = InternalInstallPlugin.install;
uninstall = InternalInstallPlugin.uninstall;
clean = [OCamlbuildPlugin.clean];
clean_test = [];
- clean_doc = [];
+ clean_doc = [("srs", OCamlbuildDocPlugin.doc_clean "lib")];
distclean = [];
distclean_test = [];
distclean_doc = [];
@@ -5661,6 +5661,34 @@ let setup_t =
lib_findlib_parent = None;
lib_findlib_name = None;
lib_findlib_containers = [];
+ });
+ Doc
+ ({
+ cs_name = "srs";
+ cs_data = PropList.Data.create ();
+ cs_plugin_data = [];
+ },
+ {
+ doc_type = (`Doc, "ocamlbuild", Some "0.3");
+ doc_custom =
+ {
+ pre_command = [(OASISExpr.EBool true, None)];
+ post_command = [(OASISExpr.EBool true, None)];
+ };
+ doc_build =
+ [
+ (OASISExpr.ENot (OASISExpr.EFlag "docs"), false);
+ (OASISExpr.EFlag "docs", true)
+ ];
+ doc_install = [(OASISExpr.EBool true, true)];
+ doc_install_dir = "$docdir";
+ doc_title = "SRS documentation";
+ doc_authors = [];
+ doc_abstract = None;
+ doc_format = OtherDoc;
+ doc_data_files = [];
+ doc_build_tools =
+ [ExternalTool "ocamlbuild"; ExternalTool "ocamldoc"];
})
];
plugins = [(`Extra, "META", Some "0.3")];
@@ -5669,14 +5697,14 @@ let setup_t =
};
oasis_fn = Some "_oasis";
oasis_version = "0.3.0";
- oasis_digest = Some "\206xh\023\201\011\229\146H(^\159\027\175\003\021";
+ oasis_digest = Some "\222\005\185\r\028\204.{XIY\003\235\127L\\";
oasis_exec = None;
oasis_setup_args = [];
setup_update = false;
};;
let setup () = BaseSetup.setup setup_t;;
-# 5681 "setup.ml"
+# 5709 "setup.ml"
(* OASIS_STOP *)
let () = setup ();;

0 comments on commit 35b45b6

Please sign in to comment.