Tiny documentation fixes 55/15655/1
authorJosé Bollo <jose.bollo@iot.bzh>
Tue, 24 Jul 2018 09:53:44 +0000 (11:53 +0200)
committerJosé Bollo <jose.bollo@iot.bzh>
Tue, 24 Jul 2018 14:28:32 +0000 (16:28 +0200)
Some english improvement of the documentation.

Change-Id: I066c41d657a1921ed7dcc46dafcc7c65d122239c
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
12 files changed:
docs/afb-application-writing.md
docs/afb-binding-writing.md
docs/afb-daemon-debugging.md
docs/afb-daemon-vocabulary.md
docs/afb-desktop-package.md
docs/afb-events-guide.md
docs/afb-migration-to-binding-v3.md
docs/afb-overview.md
docs/reference-v3/func-api.md
docs/reference-v3/func-req.md
docs/reference-v3/func-service.md
docs/reference-v3/types-and-globals.md

index cfce717..0434c50 100644 (file)
@@ -41,13 +41,13 @@ C applications can use afb-daemon binder through a websocket connection.
 The library **libafbwsc** is provided for C clients that need
 to connect with an afb-daemon binder.
 
 The library **libafbwsc** is provided for C clients that need
 to connect with an afb-daemon binder.
 
-The program **afb-client-demo** is the C example that use
+The program **afb-client-demo** is the C example that uses the
 **libafbwsc** library.  
 Source code is available here
 [src/afb-client-demo.c](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=src/afb-client-demo.c).
 
 Current implementation relies on libsystemd and file descriptors.  
 **libafbwsc** library.  
 Source code is available here
 [src/afb-client-demo.c](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=src/afb-client-demo.c).
 
 Current implementation relies on libsystemd and file descriptors.  
-This model might be review in the future to support secure sockets
+This model may be reviewed in the future to support secure sockets
 and get rid of libsystemd dependency.
 
 ### Handling sessions within applications
 and get rid of libsystemd dependency.
 
 ### Handling sessions within applications
@@ -56,7 +56,7 @@ Applications should understand sessions and token management when interacting
 with afb-daemon binder.
 
 Applications communicate with their private binder (afb-daemon) using
 with afb-daemon binder.
 
 Applications communicate with their private binder (afb-daemon) using
-a network connection or potentially any other connection channel.  
+a network connection or any other potential connection channel.  
 While the current version does not yet implement Unix socket,
 this feature might be added in the near future.  
 Developers need to be warn that HTTP protocol is a none
 While the current version does not yet implement Unix socket,
 this feature might be added in the near future.  
 Developers need to be warn that HTTP protocol is a none
@@ -65,7 +65,7 @@ clients is not supported.
 
 For this reason, the binder should authenticate the application
 by using a shared secret.  
 
 For this reason, the binder should authenticate the application
 by using a shared secret.  
-The secret is named "token" and the identification of client is named "session".
+The secret is named "token" and the identification of client is named "session.”
 
 The examples **token-websock.qml** and **afb-client** are demonstrating
 how authentication and sessions are managed.
 
 The examples **token-websock.qml** and **afb-client** are demonstrating
 how authentication and sessions are managed.
@@ -77,7 +77,7 @@ instances.
 This is especially important for bindings running as services
 as they may typically have to keep each client's data separated.
 
 This is especially important for bindings running as services
 as they may typically have to keep each client's data separated.
 
-For HTML5 applications, the web runtime handles the cookie of session
+For HTML5 applications, the web runtime handles the cookie of the session
 that the binder afb-daemon automatically sets.
 
 Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
 that the binder afb-daemon automatically sets.
 
 Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in
index 69090e3..e1401d8 100644 (file)
@@ -1,21 +1,20 @@
 # Overview of the bindings
 
 # Overview of the bindings
 
-The ***binder*** serves files through HTTP protocol and offers to
-developers the capability to offer application API methods through HTTP or
+The ***binder*** serves files through HTTP protocol and offers developers the capability to offer application API methods through HTTP or
 WebSocket protocol.
 
 The ***bindings*** are used to add **API** to ***binders***.  
 This part describes how to write a ***binding*** for ***binder***
 or in other words how to add a new **API** to the system.
 
 WebSocket protocol.
 
 The ***bindings*** are used to add **API** to ***binders***.  
 This part describes how to write a ***binding*** for ***binder***
 or in other words how to add a new **API** to the system.
 
-Excepting this summary, this section target developers.
+This section target developers.
 
 This section shortly explain how to write a binding
 using the C programming language.
 
 It is convenient to install the ***binder*** on the
 desktop used for writing the binding.  
 
 This section shortly explain how to write a binding
 using the C programming language.
 
 It is convenient to install the ***binder*** on the
 desktop used for writing the binding.  
-It allows easy debug and test.
+It allows for easy debug and test.
 
 ## Nature of a binding
 
 
 ## Nature of a binding
 
@@ -28,7 +27,7 @@ The **API** is designated and accessed through its name.
 It contains several **verbs** that implement the ***binding***
 functionalities.  
 Each of these **verbs** is a **method** that
 It contains several **verbs** that implement the ***binding***
 functionalities.  
 Each of these **verbs** is a **method** that
-processes requests of applications and sends result.
+processes requests of applications and sends results.
 
 The ***binding***'s methods are invoked by HTTP or websocket
 requests.
 
 The ***binding***'s methods are invoked by HTTP or websocket
 requests.
@@ -139,7 +138,7 @@ This shows basic things:
 
 - The include to get for creating a binding
 - How to declare the API offered by the binding
 
 - The include to get for creating a binding
 - How to declare the API offered by the binding
-- How to handle request made to the binding
+- How to handle requests made to the binding
 
 ### Getting declarations for the binding
 
 
 ### Getting declarations for the binding
 
index 4cf62be..79a7d04 100644 (file)
@@ -1,7 +1,7 @@
 # Debugging binder and bindings
 
 When compiled with the symbol AGL_DEVEL defined, the ***binder***
 # Debugging binder and bindings
 
 When compiled with the symbol AGL_DEVEL defined, the ***binder***
-understand the 2 configuration variables:
+understands the 2 configuration variables:
 
  - AFB_DEBUG_BREAK: to emit interrupts
  - AFB_DEBUG_WAIT: to wait interrupts
 
  - AFB_DEBUG_BREAK: to emit interrupts
  - AFB_DEBUG_WAIT: to wait interrupts
@@ -20,7 +20,7 @@ wait at the points **start-load** and **start-exec**.
 
 The items of the list can be separated using comma, space, tab or new-line.
 
 
 The items of the list can be separated using comma, space, tab or new-line.
 
-The break/wait points are, in the order of their occurence:
+The break/wait points are, in the order of their occurrence:
 
 - main-entry: before decode arguments
 - main-args: before daemon setup
 
 - main-entry: before decode arguments
 - main-args: before daemon setup
index 8472570..d28699b 100644 (file)
@@ -6,12 +6,12 @@ A shared library object intended to add a functionality to an afb-daemon
 instance.
 It implements an API and may provide a service.
 
 instance.
 It implements an API and may provide a service.
 
-Binding made for services can have specific entry point called after
+Binding made for services can have specific entry points called after
 initialization and before serving.
 
 ## Event
 
 initialization and before serving.
 
 ## Event
 
-Message with data propagated from the services to the client and not expecting
+Messages with data propagated from the services to the client and not expecting
 any reply.
 
 The current implementation allows to widely broadcast events to all clients.
 any reply.
 
 The current implementation allows to widely broadcast events to all clients.
index 832f41e..7c1217a 100644 (file)
@@ -1,6 +1,6 @@
 # Desktop packages for binder development
 
 # Desktop packages for binder development
 
-It exists packages of the ***binder*** (afb-daemon)
+Packages of the ***binder*** (afb-daemon)exist
 for common desktop linux distributions.
 
 - Fedora
 for common desktop linux distributions.
 
 - Fedora
index 1b3d559..3d9bf57 100644 (file)
@@ -1,7 +1,7 @@
 # Guide for developing with events
 
 Signaling agents are services that send events to any clients that
 # Guide for developing with events
 
 Signaling agents are services that send events to any clients that
-subscribed for receiving it.
+are subscribed to receive it.
 The sent events carry any data.
 
 To have a good understanding of how to:
 The sent events carry any data.
 
 To have a good understanding of how to:
@@ -34,7 +34,7 @@ a “binding” are similar.
 Subscription must :
 
 1. Create resources for generating the data.
 Subscription must :
 
 1. Create resources for generating the data.
-1. Delivering the data to the client.
+1. Deliver the data to the client.
 
 These two aspects are not handled by the same piece of software.
 
 
 These two aspects are not handled by the same piece of software.
 
@@ -43,13 +43,13 @@ These two aspects are not handled by the same piece of software.
 
 When a client subscribes for data, the agent must:
 
 
 When a client subscribes for data, the agent must:
 
-1. check that the subscription request is correct.
-1. establish the computation chain of the required data (if not already done).
-1. create a named event for the computed data (if not already done).
-1. ask the framework to establish the subscription to the event for the request.
-1. optionally give indications about the event in the reply to the client.
+1. Check that the subscription request is correct.
+1. Establish the computation chain of the required data (if not already done).
+1. Create a named event for the computed data (if not already done).
+1. Ask the framework to establish the subscription to the event for the request.
+1. Optionally give indications about the event in the reply to the client.
 
 
-The first two steps are not involving the framework.
+The first two steps do not involve the framework.
 They are linked to the business logic of the binding.
 The request can be any description of the requested data
 and the computing stream can be of any nature,
 They are linked to the business logic of the binding.
 The request can be any description of the requested data
 and the computing stream can be of any nature,
@@ -283,7 +283,7 @@ appropriate service enable parking brake.).
 
 ### Event handlers
 
 
 ### Event handlers
 
-The apis functions allow to declare event handling callbacks. These callback are
+The apis functions allow to declare event handling callbacks. These callbacks are
 called on reception of an  event matching a pattern and a receive in more that
 the event name and its companion JSON data, a user defiend closure and the api
 that is used to create it.
 called on reception of an  event matching a pattern and a receive in more that
 the event name and its companion JSON data, a user defiend closure and the api
 that is used to create it.
index 266a8b0..f7e09fd 100644 (file)
@@ -6,12 +6,12 @@ for the following reasons:
 
 - integration of the security requirements within the bindings
 - simplification of the API (after developer feedbacks)
 
 - integration of the security requirements within the bindings
 - simplification of the API (after developer feedbacks)
-- removal of obscure features, cleanup
+- removal of obscure features and cleanup
 
 The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination.  
 Thus moving from v1 or v2 to v3 is not enforced at this time. But ...
 
 
 The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination.  
 Thus moving from v1 or v2 to v3 is not enforced at this time. But ...
 
-In the face to face meeting of Karlsruhe it was decided to remove support
+In the face to face meeting in Karlsruhe it was decided to remove support
 of bindings v1 and to deprecate the use of bindings v2.
 
 So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
 of bindings v1 and to deprecate the use of bindings v2.
 
 So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
@@ -19,7 +19,7 @@ So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3**
 This guide covers the migration of bindings from version 2 to version 3.
 
 The migration from version 1 is not treated here because bindings version 1
 This guide covers the migration of bindings from version 2 to version 3.
 
 The migration from version 1 is not treated here because bindings version 1
-are very old and probably does not exist anymore. If needed you can refer
+are very old and probably do not exist anymore. If needed you can refer
 to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.html).
 
 
 to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.html).
 
 
index 2682d8d..44a5b1f 100644 (file)
@@ -31,7 +31,7 @@ The shown elements are:
 
 - The SECURITY CONTEXT
 
 
 - The SECURITY CONTEXT
 
-  The primary intend of any ***binder*** is to provide
+  The primary intention of any ***binder*** is to provide
   a secured environment for any application.  
   On AGL, the   **security context** is ensured by [Smack] 
   , the security context of the application or service.
   a secured environment for any application.  
   On AGL, the   **security context** is ensured by [Smack] 
   , the security context of the application or service.
index 0ba141d..2f836ca 100644 (file)
@@ -56,7 +56,7 @@ void afb_api_set_userdata(
 ```C
 /**
  * Check that it requires the API of 'name'.
 ```C
 /**
  * Check that it requires the API of 'name'.
- * If 'initialized' is not zero it request the API to be
+ * If 'initialized' is not zero it requests the API to be
  * initialized, implying its initialization if needed.
  * 
  * Calling this function is only allowed within init.
  * initialized, implying its initialization if needed.
  * 
  * Calling this function is only allowed within init.
@@ -199,7 +199,7 @@ void afb_api_verbose(
  * Get the root directory file descriptor. This file descriptor can
  * be used with functions 'openat', 'fstatat', ...
  *
  * Get the root directory file descriptor. This file descriptor can
  * be used with functions 'openat', 'fstatat', ...
  *
- * CAUTION, manipulate this this descriptor with care, in particular, don't close
+ * CAUTION, manipulate this descriptor with care, in particular, don't close
  * it.
  *
  * This can be used to get the path of the root directory using:
  * it.
  *
  * This can be used to get the path of the root directory using:
index 93fac28..2564405 100644 (file)
@@ -805,7 +805,7 @@ void afb_req_subcall_legacy(
  *
  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
  * This call is made in the context of the request 'req'.
  *
  * Makes a call to the method of name 'api' / 'verb' with the object 'args'.
  * This call is made in the context of the request 'req'.
- * This call is synchronous, it waits untill completion of the request.
+ * This call is synchronous, it waits until completion of the request.
  * It returns 0 on success or a negative value on error answer.
  * The object pointed by 'result' is filled and must be released by the caller
  * after its use by calling 'json_object_put'.
  * It returns 0 on success or a negative value on error answer.
  * The object pointed by 'result' is filled and must be released by the caller
  * after its use by calling 'json_object_put'.
index 939c287..2faa7bc 100644 (file)
@@ -2,7 +2,7 @@ Functions of class **afb_service**
 ==============================
 
 All the functions of the class **afb_daemon** use the default api.
 ==============================
 
 All the functions of the class **afb_daemon** use the default api.
-This are internally aliased to the corresponding legacy function of
+These are internally aliased to the corresponding legacy function of
 class **afb_api**.
 
 ```C
 class **afb_api**.
 
 ```C
index dc50b97..50abeec 100644 (file)
@@ -2,7 +2,7 @@
 
 ## The global afbBindingRoot
 
 
 ## The global afbBindingRoot
 
-The global **afbBindingRoot** of type **afb_api_t** is always implicitely
+The global **afbBindingRoot** of type **afb_api_t** is always implicitly
 defined for bindings of version 3 or upper. It records the root api of
 the binding.
 
 defined for bindings of version 3 or upper. It records the root api of
 the binding.