From 8aeddd8b944ae6e79524e11f697688ef4c5e6bea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Loi=CC=88c=20Correnson?= <loic.correnson@cea.fr>
Date: Fri, 15 Mar 2019 16:13:32 +0100
Subject: [PATCH] [doc/server] hints on naming constraints
---
src/plugins/server/data.ml | 2 +-
src/plugins/server/data.mli | 8 ++++++++
src/plugins/server/request.ml | 4 ++--
src/plugins/server/request.mli | 25 ++++++++++++++++++-------
src/plugins/server/syntax.ml | 4 ++--
src/plugins/server/syntax.mli | 5 +++--
6 files changed, 34 insertions(+), 14 deletions(-)
diff --git a/src/plugins/server/data.ml b/src/plugins/server/data.ml
index 41eb70d929b..7da6f18baad 100644
--- a/src/plugins/server/data.ml
+++ b/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
diff --git a/src/plugins/server/data.mli b/src/plugins/server/data.mli
index ca76a074c96..def45ecd812 100644
--- a/src/plugins/server/data.mli
+++ b/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
diff --git a/src/plugins/server/request.ml b/src/plugins/server/request.ml
index 29e9bbbb2b8..bd42c1c596e 100644
--- a/src/plugins/server/request.ml
+++ b/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 --- *)
diff --git a/src/plugins/server/request.mli b/src/plugins/server/request.mli
index 966f7da9b70..95b56b0115b 100644
--- a/src/plugins/server/request.mli
+++ b/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
diff --git a/src/plugins/server/syntax.ml b/src/plugins/server/syntax.ml
index 77d5bea9528..e3f22de172c 100644
--- a/src/plugins/server/syntax.ml
+++ b/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 ]
diff --git a/src/plugins/server/syntax.mli b/src/plugins/server/syntax.mli
index efcced7984f..d1f0401bea3 100644
--- a/src/plugins/server/syntax.mli
+++ b/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
(* -------------------------------------------------------------------------- *)
--
GitLab