[doc/server] hints on naming constraints

src/plugins/server/data.ml

@@ -254,7 +254,7 @@ struct
       | Some v -> Fmap.add name (D.to_json v) r in
     { member ; getter ; setter }
 
-  let fields () = Syntax.fields ~kind:"Field" !fdocs
+  let fields () = Syntax.fields ~title:"Field" !fdocs
 
   let syntax =
     Syntax.publish ~page:R.page ~name:R.name

src/plugins/server/data.mli

@@ -36,6 +36,14 @@ sig
   val to_json : t -> json
 end
 
+
+(** Datatype registration.
+
+    Name and page must be consistent with each other:
+     - The name must be lowercase, dash-separated list of identifiers
+     - Protocol data must start with ["<server>-*"]
+     - Plugin data must start with ["<plugin>-*"]
+*)
 module type Info =
 sig
   val page : Doc.page

src/plugins/server/request.ml

@@ -206,14 +206,14 @@ let doc_input (type a) (input : a rq_input) : Markdown.block =
   match input with
   | Pnone -> assert false
   | Pdata _ -> Markdown.empty
-  | Pfields fs -> Syntax.fields ~kind:"Input" (List.rev fs)
+  | Pfields fs -> Syntax.fields ~title:"Input" (List.rev fs)
 
 (* json output syntax *)
 let doc_output (type b) (output : b rq_output) : Markdown.block =
   match output with
   | Rnone -> assert false
   | Rdata _ -> Markdown.empty
-  | Rfields fs -> Syntax.fields ~kind:"Output" (List.rev fs)
+  | Rfields fs -> Syntax.fields ~title:"Output" (List.rev fs)
 
 (* -------------------------------------------------------------------------- *)
 (* --- Multi-Parameters Requests                                          --- *)

src/plugins/server/request.mli

@@ -46,7 +46,17 @@ type 'b output = (module Output with type t = 'b)
 
 (** {2 Simple Requests Registration} *)
 
-(** Register a simple request of type [(a -> b)]. *)
+(** Register a simple request of type [(a -> b)].
+
+    Name, page and kind must be consistent with each others:
+     - No publication on [`Protocol] pages
+     - Kernel requests shall starts with ["Kernel.*"]
+     - Plugin requests shall starts with ["<Plugin>.*"]
+     - GET requests must contain ["get"] or ["print"] (case insensitive)
+     - SET requests must contain ["set"] (case insensitive)
+     - EXEC requests must contain ["exec"] (case insensitive)
+
+*)
 val register :
   page:Doc.page ->
   kind:kind ->
@@ -72,12 +82,13 @@ val register :
     function:
 
     {[
+      (* ---- Exemple of Request Registration --- *)
       let () =
         let s = Request.signature ~page ~kind ~name ~descr () in
-        let get_a = Request.param s ~name:"a" ~descr:"…" (module A) in
-        let get_b = Request.param s ~name:"b" ~descr:"…" (module B) in
-        let set_c = Request.result s ~name:"c" ~descr:"…" (module C) in
-        let set_d = Request.result s ~name:"d" ~descr:"…" (module D) in
+        let get_a = Request.param s ~name:"a" ~descr:"..." (module A) in
+        let get_b = Request.param s ~name:"b" ~descr:"..." (module B) in
+        let set_c = Request.result s ~name:"c" ~descr:"..." (module C) in
+        let set_d = Request.result s ~name:"d" ~descr:"..." (module D) in
         Request.register_sig s
           (fun rq () ->
              let (c,d) = some_job (get_a rq) (get_b rq) in
@@ -130,7 +141,7 @@ val register_sig : ('a,'b) signature -> (rq -> 'a -> 'b) -> unit
     [
 
         API:                    Input JSON   OCaml Getter
-        -----------------------------------------------------
+        -----------------------------------------------------------------------
         Request.param            { f: a  }    'a (* might raise an exception *)
         Request.param ~default   { f: a? }    'a (* defined by default *)
         Request.param_opt        { f: a? }    'a option
@@ -142,7 +153,7 @@ val register_sig : ('a,'b) signature -> (rq -> 'a -> 'b) -> unit
     [
 
         API:                    Input JSON   OCaml Setter
-        ----------------------------------------------------
+        ----------------------------------------------------------------------
         Request.result           { f: a  }    'a (* shall be set by process *)
         Request.result ~default  { f: a  }    'a (* defined by default *)
         Request.param_opt        { f: a? }    'a option

src/plugins/server/syntax.ml

@@ -116,8 +116,8 @@ type field = {
   descr : Markdown.text ;
 }
 
-let fields ~kind (fds : field list) =
-  let c_field = `Left kind in
+let fields ~title (fds : field list) =
+  let c_field = `Left title in
   let c_format = `Center "Format" in
   let c_descr = `Left "Description" in
   Markdown.table [ c_field ; c_format ; c_descr ]

src/plugins/server/syntax.mli

@@ -52,7 +52,8 @@ val record : (string * t) list -> t
 
 type field = { name : string ; syntax : t ; descr : Markdown.text }
 
-(** Builds a table with fields column named « Kind » *)
-val fields : kind:string -> field list -> Markdown.block
+(** Builds a table with fields column named with [~title]
+    (shall be capitalized) *)
+val fields : title:string -> field list -> Markdown.block
 
 (* -------------------------------------------------------------------------- *)