From f064c84d457677c491f045d6c98bd7bb4f51114d Mon Sep 17 00:00:00 2001
From: Michele Alberti <michele.alberti@cea.fr>
Date: Thu, 19 Mar 2020 12:04:48 +0100
Subject: [PATCH] [server] Just a pass on API comments/doc.
---
src/plugins/server/data.mli | 79 +++++++++++++++----------------
src/plugins/server/doc.mli | 9 ++--
src/plugins/server/jbuffer.mli | 4 +-
src/plugins/server/kernel_ast.mli | 4 +-
src/plugins/server/main.mli | 29 +++++-------
src/plugins/server/request.mli | 22 ++++-----
src/plugins/server/states.mli | 34 ++++++-------
7 files changed, 85 insertions(+), 96 deletions(-)
diff --git a/src/plugins/server/data.mli b/src/plugins/server/data.mli
index 98277a45c1e..bac87bebda5 100644
--- a/src/plugins/server/data.mli
+++ b/src/plugins/server/data.mli
@@ -26,44 +26,41 @@
(* -------------------------------------------------------------------------- *)
(** {2 Datatypes}
- This module is responsible for marshaling and demarshaling data
- to handle communications between the server and the client in both
- directions.
+ This module is responsible for marshaling and demarshaling data to handle
+ communications between the server and the client in both directions.
- Each datatype must be equipped with function to
- encode and decode values to/from JSON format.
- Moreover, data types shall be also properly documented and registered
- in the generated documentation of the Frama-C server.
+ Each datatype must be equipped with functions to encode and decode values
+ to/from JSON format. Moreover, data types shall be also properly documented
+ and registered in the generated documentation of the Frama-C server.
- Generally speaking, we will have a module with signature [Data.D] for
- every datatype to be exchanged with the server. For simple values,
- predefined modules are already provided. More complex datatypes can be
- built with some functors, typically for options, lists or arrays.
+ Generally speaking, we will have a module with signature [Data.D] for every
+ datatype to be exchanged with the server. For simple values, predefined
+ modules are already provided. More complex datatypes can be built with some
+ functors, typically for options, lists or arrays.
Records and enumerated types are typical in JSON formatting, but difficult
to build from OCaml records and abstract datatypes. For those kinds of data,
we provide an API based on the following general scheme:
- - you first create a empty container with its name, documentation and such;
- - then you add each field or constructor to the container;
- - finally you pack the container, which actually registers its complete
- documentation and returns an OCaml value containing the resulting
- datatype module.
-
- Hence, in addition to module signature [Data.S] for values,
- there is also a polymorphic type ['a Data.data] for module
- values carrying a data module with type [t = 'a].
-
- The same mechanism is used throughout modules [States] and [Request]
- each time a JSON record or tag is needed.
-*)
+ - First create an empty container with its name, documentation and such;
+ - Then add each field or constructor to the container;
+ - Finally pack the container, which actually registers its complete
+ documentation and returns an OCaml value containing the resulting datatype
+ module.
+
+ Hence, in addition to module signature [Data.S] for values, there is also a
+ polymorphic type ['a Data.data] for module values carrying a data module with
+ type [t = 'a].
+
+ The same mechanism is used throughout modules [States] and [Request] each
+ time a JSON record or tag is needed. *)
(* -------------------------------------------------------------------------- *)
type json = Json.t
-val page : Doc.page (** Documentation page for general purpose data types *)
+val page : Doc.page (** Documentation page for general purpose data types. *)
val pretty : Format.formatter -> json -> unit
-(** Datatype module signature *)
+(** Datatype module signature. *)
module type S =
sig
type t
@@ -81,7 +78,7 @@ sig
val descr : Markdown.text
end
-(** Polymorphic data value *)
+(** Polymorphic data value. *)
type 'a data = (module S with type t = 'a)
(* -------------------------------------------------------------------------- *)
@@ -109,7 +106,7 @@ module Jint : S_collection with type t = int
module Jfloat : S_collection with type t = float
module Jstring : S_collection with type t = string
module Jident : S_collection with type t = string (** Syntax is {i ident}. *)
-module Jtext : S with type t = json (** Rich text encoding, see [Jbuffer] *)
+module Jtext : S with type t = json (** Rich text encoding, see [Jbuffer]. *)
module Jmarkdown : S with type t = Markdown.text
(* -------------------------------------------------------------------------- *)
@@ -153,9 +150,9 @@ module Jarray(A : S) : S with type t = A.t array
module Record :
sig
- type 'a record (** Records of type 'a *)
- type 'a signature (** Opened signature for record of type ['a] *)
- type ('a,'b) field (** Field of type ['b] for a record of type ['a] *)
+ type 'a record (** Records of type ['a]. *)
+ type 'a signature (** Opened signature for record of type ['a]. *)
+ type ('a,'b) field (** Field of type ['b] for a record of type ['a]. *)
(** Data with [type t = r record].
Also contains getters and setters for fields. *)
@@ -169,21 +166,21 @@ sig
val set : (r,'a) field -> 'a -> t -> t
end
- (** Create a new, opened record type *)
+ (** Create a new, opened record type. *)
val signature : page:Doc.page -> name:string -> descr:Markdown.text ->
unit -> 'a signature
- (** Adds a field to an opened record *)
+ (** Adds a field to an opened record. *)
val field : 'r signature ->
name:string -> descr:Markdown.text -> ?default:'a -> 'a data ->
('r,'a) field
- (** Adds a optional field to an opened record *)
+ (** Adds a optional field to an opened record. *)
val option : 'r signature ->
name:string -> descr:Markdown.text -> 'a data ->
('r,'a option) field
- (** Publish and close an opened record *)
+ (** Publish and close an opened record. *)
val publish : 'a signature ->
(module S with type r = 'a)
@@ -293,7 +290,7 @@ end
*)
(* -------------------------------------------------------------------------- *)
-(** Simplified [Map.S] *)
+(** Simplified [Map.S]. *)
module type Map =
sig
type 'a t
@@ -308,7 +305,7 @@ module type Index =
sig
include S_collection
val get : t -> int
- val find : int -> t (** @raise Not_found if not registered *)
+ val find : int -> t (** @raise Not_found if not registered. *)
val clear : unit -> unit
(** Clear index tables. Use with extreme care. *)
end
@@ -327,7 +324,7 @@ sig
include Info
end
-(** Builds a {i projectified} index on types with {i unique} identifiers *)
+(** Builds a {i projectified} index on types with {i unique} identifiers. *)
module Identified(A : IdentifiedType) : Index with type t = A.t
(* -------------------------------------------------------------------------- *)
@@ -338,13 +335,13 @@ module Identified(A : IdentifiedType) : Index with type t = A.t
*)
(* -------------------------------------------------------------------------- *)
-(** Exception thrown during the decoding of a request's inputs *)
+(** Exception thrown during the decoding of a request's inputs. *)
exception InputError of string
val failure : ?json:json -> ('a, Format.formatter, unit, 'b) format4 -> 'a
-(** @raise InputError with provided message *)
+(** @raise InputError with provided message. *)
val failure_from_type_error : string -> json -> 'a
-(** @raise InputError from Yojson.Basic.Util.Type_error arguments *)
+(** @raise InputError from [Yojson.Basic.Util.Type_error] arguments. *)
(* -------------------------------------------------------------------------- *)
diff --git a/src/plugins/server/doc.mli b/src/plugins/server/doc.mli
index d3f3d2978be..99bac4c4df9 100644
--- a/src/plugins/server/doc.mli
+++ b/src/plugins/server/doc.mli
@@ -48,8 +48,8 @@ val page : chapter -> title:string -> filename:string -> page
(** Adds a section in the corresponding page.
Returns an href to the published section.
- If index items are provided, they are added
- to the server documentation index.
+ If index items are provided, they are added to the server documentation
+ index.
*)
val publish :
page:page ->
@@ -60,9 +60,8 @@ val publish :
?generated:(unit -> Markdown.elements) ->
unit -> Markdown.href
-(** Dumps all published pages of documentations. Unless [~meta:false],
- also generates METADATA for each page in
- [<filename>.json] for each page. *)
+(** Dumps all published pages of documentations. Unless [~meta:false], also
+ generates METADATA for each page in [<filename>.json] for each page. *)
val dump : root:string -> ?meta:bool -> unit -> unit
(* -------------------------------------------------------------------------- *)
diff --git a/src/plugins/server/jbuffer.mli b/src/plugins/server/jbuffer.mli
index b17f318b567..9db8cfab7ea 100644
--- a/src/plugins/server/jbuffer.mli
+++ b/src/plugins/server/jbuffer.mli
@@ -43,7 +43,7 @@ val create : ?indent:int -> ?margin:int -> unit -> buffer
(** The underlying formatter of a buffer. *)
val formatter : buffer -> Format.formatter
-(** Prints into the buffer's formatter. *)
+(** Prints into the buffer formatter. *)
val bprintf : buffer -> ('a,Format.formatter,unit) format -> 'a
val append : buffer -> string -> int -> int -> unit
@@ -55,7 +55,7 @@ val pop_tag : buffer -> Transitioning.Format.stag -> unit
tags. *)
val contents : buffer -> json
-(** Prints back a JSON encoding onto the provided formatter.
+(** Prints back a JSON encoding into the provided formatter.
@raise Yojson.Basic.Util.Type_error in case of ill formatted buffer. *)
val fprintf : Format.formatter -> json -> unit
diff --git a/src/plugins/server/kernel_ast.mli b/src/plugins/server/kernel_ast.mli
index bca1b211f0f..f683fabe5ed 100644
--- a/src/plugins/server/kernel_ast.mli
+++ b/src/plugins/server/kernel_ast.mli
@@ -33,8 +33,8 @@ module Stmt : Data.S_collection with type t = stmt
module Marker :
sig
include Data.S with type t = Printer_tag.localizable
- val create : t -> string (** memoized unique identifier *)
- val lookup : string -> t (** get back the localizable, if any *)
+ val create : t -> string (** Memoized unique identifier. *)
+ val lookup : string -> t (** Get back the localizable, if any. *)
end
(* -------------------------------------------------------------------------- *)
diff --git a/src/plugins/server/main.mli b/src/plugins/server/main.mli
index 0dec3960aba..eec63fefa2b 100644
--- a/src/plugins/server/main.mli
+++ b/src/plugins/server/main.mli
@@ -35,7 +35,7 @@ val pp_kind : Format.formatter -> kind -> unit
val register : kind -> string -> (json -> json) -> unit
val find : string -> (kind * (json -> json)) option
-val exec : string -> json -> json (** @raises Not_found if not registered *)
+val exec : string -> json -> json (** @raises Not_found if not registered. *)
(* -------------------------------------------------------------------------- *)
(** {2 Signals Registry} *)
@@ -78,13 +78,10 @@ type 'a message = {
type 'a server
-(**
- Run a server with the provided low-level network primitives to
- actually exchange data. Logs are monitored unless [~logs:false]
- is specified.
+(** Run a server with the provided low-level network primitives to actually
+ exchange data. Logs are monitored unless [~logs:false] is specified.
- Default equality is the standard `(=)` one.
-*)
+ Default equality is the standard `(=)` one. *)
val create :
pretty:(Format.formatter -> 'a -> unit) ->
?equal:('a -> 'a -> bool) ->
@@ -92,24 +89,22 @@ val create :
unit -> 'a server
(** Run the server forever.
- The function will {i not} return until the server is actually
- shut down. *)
+ The function will {i not} return until the server is actually shut down. *)
val run : 'a server -> unit
(** Start the server in background.
- The function returns immediately
- after installing a daemon that accepts GET requests received by
- the server on calls to `Db.yield()`.
-*)
+
+ The function returns immediately after installing a daemon that accepts GET
+ requests received by the server on calls to [Db.yield()]. *)
val start : 'a server -> unit
(** Stop the server if it is running in background. *)
val stop : 'a server -> unit
-(** Kills the currently running request. Actually raises an exception. *)
+(** Kill the currently running request by raising an exception. *)
val kill : unit -> 'a
-(** Emits the server signal to the client. *)
+(** Emit the server signal to the client. *)
val emit : signal -> unit
(** Register a callback on signal listening.
@@ -120,8 +115,8 @@ val emit : signal -> unit
val on_signal : signal -> (bool -> unit) -> unit
(** Register a callback to listen for server activity.
- All callbacks would be executed in their order of registration.
- They shall {i never} raise any exception. *)
+ All callbacks are executed in their order of registration.
+ Callbacks shall {i never} raise any exception. *)
val on : (bool -> unit) -> unit
(* -------------------------------------------------------------------------- *)
diff --git a/src/plugins/server/request.mli b/src/plugins/server/request.mli
index 4b44faf54b2..d3c120adf9e 100644
--- a/src/plugins/server/request.mli
+++ b/src/plugins/server/request.mli
@@ -48,13 +48,12 @@ type 'b output = (module Output with type t = 'b)
A signal is a one-way message from server to client for indicating that
something happened. To avoid unecessary noise, the client must be registered
- on each of signal it is interested in. The client will then send a proper get
+ on each signal it is interested in. The client will then send a proper get
requests to the server to retrieve the updated data.
As a matter of fact, update events are much more frequent than what a
- typical GUI client can handle. Hence, signal emissions can not carry data
- and are grouped (or « debounced ») until the next server
- response to client. *)
+ typical GUI client can handle. Hence, signal emissions can not carry data and
+ are grouped (or « debounced ») until the next server response to client. *)
(** The type of registered signals. *)
type signal
@@ -192,8 +191,8 @@ val register_sig : ('a,'b) signature -> (rq -> 'a -> 'b) -> unit
*)
-(** Named input parameter. If a default value is provided,
- the JSON input field becomes optional. Otherwized, it is required. *)
+(** Named input parameter. If a default value is provided, the JSON input field
+ becomes optional. Otherwized, it is required. *)
val param : (unit,'b) signature ->
name:string ->
descr:Markdown.text ->
@@ -206,10 +205,9 @@ val param_opt : (unit,'b) signature ->
descr:Markdown.text ->
'a input -> 'a option param
-(** Named output parameter. If a default value is provided,
- the JSON output field is initialized with it.
- Otherwized, it shall be set at each invocation of the request processing
- funciton. *)
+(** Named output parameter. If a default value is provided, the JSON output
+ field is initialized with it. Otherwise, it shall be set at each invocation
+ of the request processing funciton. *)
val result : ('a,unit) signature ->
name:string ->
descr:Markdown.text ->
@@ -224,8 +222,8 @@ val result_opt : ('a,unit) signature ->
(** {2 Exporting Dictionaries} *)
-(** Register a [GET] request [dictionary.<name>] to retrieve all tags
- registered in the dictionary. *)
+(** Register a [GET] request [dictionary.<name>] to retrieve all tags registered
+ in the dictionary. *)
val dictionary : 'a Data.Enum.dictionary -> unit
(* -------------------------------------------------------------------------- *)
diff --git a/src/plugins/server/states.mli b/src/plugins/server/states.mli
index 7224c3bac63..00dabb46631 100644
--- a/src/plugins/server/states.mli
+++ b/src/plugins/server/states.mli
@@ -20,7 +20,7 @@
(* *)
(**************************************************************************)
-(** Synchronized values between Server & Client *)
+(** Synchronized values between Server and Client *)
type 'a callback = ('a -> unit) -> unit
@@ -29,9 +29,9 @@ type 'a callback = ('a -> unit) -> unit
- Signal [<name>.sig] is emitted on value updates;
- GET Request [<name>.get] returns the current value.
- If provided, the [~add_hook] option is used to register a hook
- to notify the server of value updates. The hook will be installed
- only once the client starts to listen for value updates.
+ If provided, the [~add_hook] option is used to register a hook to notify the
+ server of value updates. The hook will be installed only once the client
+ starts to listen for value updates.
Inside {b Ivette} you can use the [States.useSyncValue(id)] hook to
synchronize with this value.
@@ -52,9 +52,9 @@ val register_value :
- GET Request [<name>.get] returns the current value;
- SET Request [<name>.set] modifies the server value.
- If provided, the [~add_hook] option is used to register a hook
- to notify the server of value updates. The hook will be installed
- only once the client starts to listen for value updates.
+ If provided, the [~add_hook] option is used to register a hook to notify the
+ server of value updates. The hook will be installed only once the client
+ starts to listen for value updates.
Inside {b Ivette} you can use the [States.useSyncState(id)] hook to
synchronize with this state.
@@ -76,8 +76,7 @@ type 'a model (** Columns array model *)
val model : unit -> 'a model
(** Populate an array model with a new field.
- Columns with name `"id"` and `"_index"` are
- reserved for internal use. *)
+ Columns with name `"id"` and `"_index"` are reserved for internal use. *)
val column :
model:'a model ->
name:string ->
@@ -86,7 +85,8 @@ val column :
get:('a -> 'b) ->
unit -> unit
-type 'a array (** Synchronized array state *)
+(** Synchronized array state. *)
+type 'a array
(** Mark the array to be fully reloaded. *)
val reload : 'a array -> unit
@@ -97,7 +97,7 @@ val update : 'a array -> 'a -> unit
(** Mark an array entry as removed. *)
val remove : 'a array -> 'a -> unit
-(** Get the signal associated with the array *)
+(** Get the signal associated with the array. *)
val signal : 'a array -> Request.signal
(** Register everything necessary to synchronize an array with
@@ -109,16 +109,16 @@ val signal : 'a array -> Request.signal
The [~key] parameter is used to identify array entries, and used to fill
the reserved column ["id"] of entries.
- Columns added to the model after registration are {i not} taken
- into account.
+ Columns added to the model after registration are {i not} taken into
+ account.
If provided, the [~add_xxx_hook] options are used to register hooks
to notify the server of corresponding array updates.
- Each hook will be installed only once the client starts to
- listen for array updates.
+ Each hook will be installed only once the client starts to listen for array
+ updates.
- Inside {b Ivette} you can obtain the entries in sync by
- using the [States.useSyncArray()] hook.
+ Inside {b Ivette} you can obtain the entries in sync by using the
+ [States.useSyncArray()] hook.
*)
val register_array :
page:Doc.page ->
--
GitLab