Commit 8eca8df7 authored by Siebers, Michael's avatar Siebers, Michael
Browse files

polish documentation

parent c7e10ffb
......@@ -133,10 +133,10 @@ curl --request GET 'http://localhost:4444/bg/show'
| =|/bg/add|= | `no` | =POST= |
#### Parameters
None.
| Argument | Example | Required | Description |
| --- | --- | --- | --- |
| _item_ or an array of _item_ | _see example call_ | Required | Asserts the arguments to the background knowledge.|
#### Request Body
A JSON document consisting either of a single [item](<#json_types>) or an array of items.
#### Return value
......@@ -188,10 +188,11 @@ In contrast to `bg/clear`, remove allows for retracting the provided items only.
| =|/bg/remove|= | `no` | =POST= |
#### Parameters
None.
#### Request Body
A JSON document consisting either of a single [item](<#json_types>) or an array of items.
| Argument | Example | Required | Description |
| --- | --- | --- | --- |
| _item_ or array of _item_ | _see example call_ | Required | Retracts the arguments from the background knowledge. |
#### Return value
......@@ -240,9 +241,10 @@ In contrast to `bg/remove`, clear resets the background knowledge completely.
| =|/bg/clear|= | `no` | =POST= |
#### Parameters
None.
#### Request Body
None.
#### Return value
......@@ -284,6 +286,10 @@ Queries whether a _single file_ is irrelevant.
| =|/irrelevant/file|= | `no` | `POST` |
#### Parameters
None.
#### Request Body
A JSON object with the following properties:
| Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- |
......@@ -325,6 +331,10 @@ Explains why an irrelevant file is irrelevant.
| =|/explain|= | `no` | =POST= |
#### Parameters
None.
#### Request Body
A JSON object with the following properties:
| Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- |
......@@ -350,7 +360,19 @@ An explanation consists of four parts:
- a top-level view reasoning why the file is irrelevant (`reasoning`),
- a detailed step-by-step reasoning why the file is irrelevant (`reasoning_details`), and
- references to the 'real-world' file system (`references`).
The `reasoning` top-level view is a text, possibly broken into multiple parts.
Each such part may reference real-world items or some specific properties of these. For example could the text part "file A.txt" be linked with the `name` property of the item with absolute path `some_directory/A.txt`.
Such references may be used in a client to display relevant information alongside the explanation, like a view of the directory a file is in. Relevant information may even be highlighted colorfully.
The `reasoning_details` is a sequence of texts forming reasoning trace, why `reasoning` is true. For example, the text sequence `A`, `B`, `C` is to be interpreted as "`reasoning` holds because A, B, and C."
Like for `reasoning`, each text may be broken into multiple parts and reference real-world items' properties.
A client may use the text sequence to form a single sentence (like in the example before) or display it as bullet list.
Technically, `references` is an array ob objects with unique identifiers and arrays of references. Each reference is an objects with the properties `abs_path` and `property`.
A text part as mentioned above, or message, is an array of objects with required property `text` and optional property `ref_id`, where `text` is any free-form string and `ref_id` is the unique identifier of an reference.
Then, `reasoning` is an array of messages and `reasoning_details` is an array of arrays of messages.
For a full description, consult the [JSON schema](</doc/schema/response-explain-schema.json>) of the response.
#### Example Call
......@@ -438,9 +460,12 @@ To receive basic information on the currently running server you may query the s
| =|/state|= | `no` | =GET= |
#### Parameters
None.
#### Request Body
None.
#### Return value
This endpoint always Return value _200 OK_ along with a JSON object describing the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment