sid.mli: document module

1 files changed, 34 insertions, 3 deletions

diff --git a/sid.mli b/sid.mli
index cffc0e9..9012df8 100644
--- a/sid.mli
+++ b/sid.mli
@@ -2,26 +2,54 @@
 
 type t
 type sub_auths = Stdint.Uint32.t array
+
+val create : ?sa:Stdint.Uint32.t array -> Stdint.Uint64.t -> t option
+(** [create sas ia] constructs a SID with the identifier authority [ia]
+    and, optionally, the subauthorities [sas]. The operation will return
+    [None] if [sa] contains more than fifteen subauthorities. *)
+
 val create_unsafe : Stdint.Uint32.t array -> Stdint.Uint64.t -> t
-val create : ?sa:Stdint.Uint32.t array -> Stdint.Uint64.t -> t
-val equal_sub_auths : Stdint.Uint32.t array -> Stdint.Uint32.t array -> bool
+(** [create_unsafe sas ia] constructs a SID with the identifier authority [ia]
+    and, optionally, the sub authorities [sas] without validating the inputs.
+    Use with caution. *)
+
 val equal : t -> t -> bool
+(** [equal sa sb] tests whether [sa] and [sb] are identical. *)
+
+val equal_sub_auths : Stdint.Uint32.t array -> Stdint.Uint32.t array -> bool
+(** [equal_sub_auths sa sb] tests whether [sa] and [sb] have identical
+    subauthorities. *)
+
 val get_ident_auth : t -> Stdint.Uint64.t
+(** [get_ident_auth s] get the identifier authority of SID [s]. *)
+
 val get_sub_auths : t -> sub_auths
+(** [get_ident_auth s] get the subauthorities array of SID [s]. *)
 
+(** Conversions to and from the {e string format syntax} (MS-DTYP 2.4.2.1). *)
 module StringFmt :
   sig
     val decode : string -> (t, string) result
+    (** [decode b] parse string buffer [b] into a SID. *)
+
     val encode : t -> string
+    (** [encode s] convert SID [s] to its string representation. *)
   end
 
+(** Conversion to and from the {e packet representation} (MS-DTYP 2.4.2.2). *)
 module PacketRep :
   sig
     type endian = Big | Little
-    val encode : ?endian:endian -> t -> bytes
     val decode : ?endian:endian -> bytes -> (t, string) result
+    (** [decode endian b] decode the byte buffer [b] as a SID. *)
+
+    val encode : ?endian:endian -> t -> bytes
+    (** [encode endian s] convert SID [s] to the packet representation
+        encoding subauthorities in endianness [endian]. *)
   end
 
+(** Pre-defined SID constansts and constructors with fixed identifier
+    authority (MS-DTYP 2.4.2.4). *)
 module WellKnown :
   sig
     val null : t
@@ -49,5 +77,8 @@ module WellKnown :
   end
 
 val of_string : string -> (t, string) result
+(** [of_string b] is an alias for [StringFmt.decode b]. *)
+
 val to_string : t -> string
+(** [to_string s] is an alias for [StringFmt.encode s]. *)