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' ...@@ -133,10 +133,10 @@ curl --request GET 'http://localhost:4444/bg/show'
| =|/bg/add|= | `no` | =POST= | | =|/bg/add|= | `no` | =POST= |
#### Parameters #### Parameters
None.
| Argument | Example | Required | Description | #### Request Body
| --- | --- | --- | --- | A JSON document consisting either of a single [item](<#json_types>) or an array of items.
| _item_ or an array of _item_ | _see example call_ | Required | Asserts the arguments to the background knowledge.|
#### Return value #### Return value
...@@ -188,10 +188,11 @@ In contrast to `bg/clear`, remove allows for retracting the provided items only. ...@@ -188,10 +188,11 @@ In contrast to `bg/clear`, remove allows for retracting the provided items only.
| =|/bg/remove|= | `no` | =POST= | | =|/bg/remove|= | `no` | =POST= |
#### Parameters #### 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 #### Return value
...@@ -240,9 +241,10 @@ In contrast to `bg/remove`, clear resets the background knowledge completely. ...@@ -240,9 +241,10 @@ In contrast to `bg/remove`, clear resets the background knowledge completely.
| =|/bg/clear|= | `no` | =POST= | | =|/bg/clear|= | `no` | =POST= |
#### Parameters #### Parameters
None. None.
#### Request Body
None.
#### Return value #### Return value
...@@ -284,6 +286,10 @@ Queries whether a _single file_ is irrelevant. ...@@ -284,6 +286,10 @@ Queries whether a _single file_ is irrelevant.
| =|/irrelevant/file|= | `no` | `POST` | | =|/irrelevant/file|= | `no` | `POST` |
#### Parameters #### Parameters
None.
#### Request Body
A JSON object with the following properties:
| Argument | Example | Type | Required | Description | | Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
...@@ -325,6 +331,10 @@ Explains why an irrelevant file is irrelevant. ...@@ -325,6 +331,10 @@ Explains why an irrelevant file is irrelevant.
| =|/explain|= | `no` | =POST= | | =|/explain|= | `no` | =POST= |
#### Parameters #### Parameters
None.
#### Request Body
A JSON object with the following properties:
| Argument | Example | Type | Required | Description | | Argument | Example | Type | Required | Description |
| --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- |
...@@ -350,7 +360,19 @@ An explanation consists of four parts: ...@@ -350,7 +360,19 @@ An explanation consists of four parts:
- a top-level view reasoning why the file is irrelevant (`reasoning`), - 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 - a detailed step-by-step reasoning why the file is irrelevant (`reasoning_details`), and
- references to the 'real-world' file system (`references`). - 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 #### Example Call
...@@ -438,9 +460,12 @@ To receive basic information on the currently running server you may query the s ...@@ -438,9 +460,12 @@ To receive basic information on the currently running server you may query the s
| =|/state|= | `no` | =GET= | | =|/state|= | `no` | =GET= |
#### Parameters #### Parameters
None.
#### Request Body
None. None.
#### Return value #### Return value
This endpoint always Return value _200 OK_ along with a JSON object describing the This endpoint always Return value _200 OK_ along with a JSON object describing the
......
Supports Markdown
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