From f44a28affea5841186250b66fd5ce72a8afbe349 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Tue, 24 Jul 2018 11:53:44 +0200 Subject: [PATCH] Tiny documentation fixes MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Some english improvement of the documentation. Change-Id: I066c41d657a1921ed7dcc46dafcc7c65d122239c Signed-off-by: José Bollo --- docs/afb-application-writing.md | 10 +++++----- docs/afb-binding-writing.md | 11 +++++------ docs/afb-daemon-debugging.md | 4 ++-- docs/afb-daemon-vocabulary.md | 4 ++-- docs/afb-desktop-package.md | 2 +- docs/afb-events-guide.md | 18 +++++++++--------- docs/afb-migration-to-binding-v3.md | 6 +++--- docs/afb-overview.md | 2 +- docs/reference-v3/func-api.md | 4 ++-- docs/reference-v3/func-req.md | 2 +- docs/reference-v3/func-service.md | 2 +- docs/reference-v3/types-and-globals.md | 2 +- 12 files changed, 33 insertions(+), 34 deletions(-) diff --git a/docs/afb-application-writing.md b/docs/afb-application-writing.md index cfce7179..0434c501 100644 --- a/docs/afb-application-writing.md +++ b/docs/afb-application-writing.md @@ -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 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. -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 @@ -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 -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 @@ -65,7 +65,7 @@ clients is not supported. 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. @@ -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. -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 diff --git a/docs/afb-binding-writing.md b/docs/afb-binding-writing.md index 69090e3d..e1401d8e 100644 --- a/docs/afb-binding-writing.md +++ b/docs/afb-binding-writing.md @@ -1,21 +1,20 @@ # 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. -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. -It allows easy debug and test. +It allows for easy debug and test. ## 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 -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. @@ -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 -- How to handle request made to the binding +- How to handle requests made to the binding ### Getting declarations for the binding diff --git a/docs/afb-daemon-debugging.md b/docs/afb-daemon-debugging.md index 4cf62bea..79a7d043 100644 --- a/docs/afb-daemon-debugging.md +++ b/docs/afb-daemon-debugging.md @@ -1,7 +1,7 @@ # 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 @@ -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 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 diff --git a/docs/afb-daemon-vocabulary.md b/docs/afb-daemon-vocabulary.md index 84725700..d28699be 100644 --- a/docs/afb-daemon-vocabulary.md +++ b/docs/afb-daemon-vocabulary.md @@ -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. -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 -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. diff --git a/docs/afb-desktop-package.md b/docs/afb-desktop-package.md index 832f41e6..7c1217a9 100644 --- a/docs/afb-desktop-package.md +++ b/docs/afb-desktop-package.md @@ -1,6 +1,6 @@ # 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 diff --git a/docs/afb-events-guide.md b/docs/afb-events-guide.md index 1b3d559d..3d9bf574 100644 --- a/docs/afb-events-guide.md +++ b/docs/afb-events-guide.md @@ -1,7 +1,7 @@ # 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: @@ -34,7 +34,7 @@ a “binding” are similar. 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. @@ -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: -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, @@ -283,7 +283,7 @@ appropriate service enable parking brake.). ### 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. diff --git a/docs/afb-migration-to-binding-v3.md b/docs/afb-migration-to-binding-v3.md index 266a8b0c..f7e09fd9 100644 --- a/docs/afb-migration-to-binding-v3.md +++ b/docs/afb-migration-to-binding-v3.md @@ -6,12 +6,12 @@ for the following reasons: - 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 ... -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** @@ -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 -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). diff --git a/docs/afb-overview.md b/docs/afb-overview.md index 2682d8d1..44a5b1f6 100644 --- a/docs/afb-overview.md +++ b/docs/afb-overview.md @@ -31,7 +31,7 @@ The shown elements are: - 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. diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md index 0ba141df..2f836cab 100644 --- a/docs/reference-v3/func-api.md +++ b/docs/reference-v3/func-api.md @@ -56,7 +56,7 @@ void afb_api_set_userdata( ```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. @@ -199,7 +199,7 @@ void afb_api_verbose( * 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: diff --git a/docs/reference-v3/func-req.md b/docs/reference-v3/func-req.md index 93fac280..25644056 100644 --- a/docs/reference-v3/func-req.md +++ b/docs/reference-v3/func-req.md @@ -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'. - * 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'. diff --git a/docs/reference-v3/func-service.md b/docs/reference-v3/func-service.md index 939c287a..2faa7bcd 100644 --- a/docs/reference-v3/func-service.md +++ b/docs/reference-v3/func-service.md @@ -2,7 +2,7 @@ Functions of class **afb_service** ============================== 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 diff --git a/docs/reference-v3/types-and-globals.md b/docs/reference-v3/types-and-globals.md index dc50b97a..50abeecb 100644 --- a/docs/reference-v3/types-and-globals.md +++ b/docs/reference-v3/types-and-globals.md @@ -2,7 +2,7 @@ ## 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. -- 2.16.6