Improve documentation

docs/development/core/public/kibana-plugin-public.md

@@ -60,7 +60,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [Plugin](./kibana-plugin-public.plugin.md) | The interface that should be returned by a <code>PluginInitializer</code>. |
 |  [PluginInitializerContext](./kibana-plugin-public.plugininitializercontext.md) | The available core services passed to a <code>PluginInitializer</code> |
 |  [SavedObject](./kibana-plugin-public.savedobject.md) |  |
-|  [SavedObjectAttributes](./kibana-plugin-public.savedobjectattributes.md) |  |
+|  [SavedObjectAttributes](./kibana-plugin-public.savedobjectattributes.md) | The data for a Saved Object is stored in the <code>attributes</code> key as either an object or an array of objects. |
 |  [SavedObjectReference](./kibana-plugin-public.savedobjectreference.md) | A reference to another saved object. |
 |  [SavedObjectsBaseOptions](./kibana-plugin-public.savedobjectsbaseoptions.md) |  |
 |  [SavedObjectsBatchResponse](./kibana-plugin-public.savedobjectsbatchresponse.md) |  |

docs/development/core/public/kibana-plugin-public.savedobject.attributes.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.attributes property
 
+The data for a Saved Object is stored in the `attributes` key as either an object or an array of objects.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.id.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.id property
 
+The ID of this Saved Object, guaranteed to be unique for all objects of the same `type`
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.md

@@ -15,12 +15,12 @@ export interface SavedObject<T extends SavedObjectAttributes = any>
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [attributes](./kibana-plugin-public.savedobject.attributes.md) | <code>T</code> |  |
+|  [attributes](./kibana-plugin-public.savedobject.attributes.md) | <code>T</code> | The data for a Saved Object is stored in the <code>attributes</code> key as either an object or an array of objects. |
 |  [error](./kibana-plugin-public.savedobject.error.md) | <code>{</code><br/><code>        message: string;</code><br/><code>        statusCode: number;</code><br/><code>    }</code> |  |
-|  [id](./kibana-plugin-public.savedobject.id.md) | <code>string</code> |  |
-|  [migrationVersion](./kibana-plugin-public.savedobject.migrationversion.md) | <code>SavedObjectsMigrationVersion</code> |  |
-|  [references](./kibana-plugin-public.savedobject.references.md) | <code>SavedObjectReference[]</code> |  |
-|  [type](./kibana-plugin-public.savedobject.type.md) | <code>string</code> |  |
-|  [updated\_at](./kibana-plugin-public.savedobject.updated_at.md) | <code>string</code> |  |
-|  [version](./kibana-plugin-public.savedobject.version.md) | <code>string</code> |  |
+|  [id](./kibana-plugin-public.savedobject.id.md) | <code>string</code> | The ID of this Saved Object, guaranteed to be unique for all objects of the same <code>type</code> |
+|  [migrationVersion](./kibana-plugin-public.savedobject.migrationversion.md) | <code>SavedObjectsMigrationVersion</code> | Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value. |
+|  [references](./kibana-plugin-public.savedobject.references.md) | <code>SavedObjectReference[]</code> | A reference to another saved object. |
+|  [type](./kibana-plugin-public.savedobject.type.md) | <code>string</code> | The type of Saved Object. Each plugin can define it's own custom Saved Object types. |
+|  [updated\_at](./kibana-plugin-public.savedobject.updated_at.md) | <code>string</code> | Timestamp of the last time this document had been updated. |
+|  [version](./kibana-plugin-public.savedobject.version.md) | <code>string</code> | An opaque version number which changes on each successful write operation. Can be used for implementing optimistic concurrency control. |
 

docs/development/core/public/kibana-plugin-public.savedobject.migrationversion.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.migrationVersion property
 
+Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.references.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.references property
 
+A reference to another saved object.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.type.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.type property
 
+The type of Saved Object. Each plugin can define it's own custom Saved Object types.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.updated_at.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.updated\_at property
 
+Timestamp of the last time this document had been updated.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobject.version.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.version property
 
+An opaque version number which changes on each successful write operation. Can be used for implementing optimistic concurrency control.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobjectattributes.md

@@ -4,6 +4,7 @@
 
 ## SavedObjectAttributes interface
 
+The data for a Saved Object is stored in the `attributes` key as either an object or an array of objects.
 
 <b>Signature:</b>
 

docs/development/core/public/kibana-plugin-public.savedobjectsfindoptions.fields.md

@@ -4,8 +4,15 @@
 
 ## SavedObjectsFindOptions.fields property
 
+An array of fields to include in the results
+
 <b>Signature:</b>
 
 ```typescript
 fields?: string[];
 ```
+
+## Example
+
+SavedObjects.find(<!-- -->{<!-- -->type: 'dashboard', fields: \['attributes.name', 'attributes.location'\]<!-- -->}<!-- -->)
+

docs/development/core/public/kibana-plugin-public.savedobjectsfindoptions.md

@@ -16,12 +16,12 @@ export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [defaultSearchOperator](./kibana-plugin-public.savedobjectsfindoptions.defaultsearchoperator.md) | <code>'AND' &#124; 'OR'</code> |  |
-|  [fields](./kibana-plugin-public.savedobjectsfindoptions.fields.md) | <code>string[]</code> |  |
+|  [fields](./kibana-plugin-public.savedobjectsfindoptions.fields.md) | <code>string[]</code> | An array of fields to include in the results |
 |  [hasReference](./kibana-plugin-public.savedobjectsfindoptions.hasreference.md) | <code>{</code><br/><code>        type: string;</code><br/><code>        id: string;</code><br/><code>    }</code> |  |
 |  [page](./kibana-plugin-public.savedobjectsfindoptions.page.md) | <code>number</code> |  |
 |  [perPage](./kibana-plugin-public.savedobjectsfindoptions.perpage.md) | <code>number</code> |  |
-|  [search](./kibana-plugin-public.savedobjectsfindoptions.search.md) | <code>string</code> |  |
-|  [searchFields](./kibana-plugin-public.savedobjectsfindoptions.searchfields.md) | <code>string[]</code> | see Elasticsearch Simple Query String Query field argument for more information |
+|  [search](./kibana-plugin-public.savedobjectsfindoptions.search.md) | <code>string</code> | Search documents using the Elasticsearch Simple Query String syntax. See Elasticsearch Simple Query String <code>query</code> argument for more information |
+|  [searchFields](./kibana-plugin-public.savedobjectsfindoptions.searchfields.md) | <code>string[]</code> | The fields to perform the parsed query against. See Elasticsearch Simple Query String <code>fields</code> argument for more information |
 |  [sortField](./kibana-plugin-public.savedobjectsfindoptions.sortfield.md) | <code>string</code> |  |
 |  [sortOrder](./kibana-plugin-public.savedobjectsfindoptions.sortorder.md) | <code>string</code> |  |
 |  [type](./kibana-plugin-public.savedobjectsfindoptions.type.md) | <code>string &#124; string[]</code> |  |

docs/development/core/public/kibana-plugin-public.savedobjectsfindoptions.search.md

@@ -4,6 +4,8 @@
 
 ## SavedObjectsFindOptions.search property
 
+Search documents using the Elasticsearch Simple Query String syntax. See Elasticsearch Simple Query String `query` argument for more information
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/public/kibana-plugin-public.savedobjectsfindoptions.searchfields.md

@@ -4,7 +4,7 @@
 
 ## SavedObjectsFindOptions.searchFields property
 
-see Elasticsearch Simple Query String Query field argument for more information
+The fields to perform the parsed query against. See Elasticsearch Simple Query String `fields` argument for more information
 
 <b>Signature:</b>
 

docs/development/core/public/kibana-plugin-public.savedobjectsmigrationversion.md

@@ -14,12 +14,5 @@ export interface SavedObjectsMigrationVersion
 
 ## Example
 
-
-```
-migrationVersion: {
-  dashboard: '7.1.1',
-  space: '6.6.6',
-}
-
-```
+migrationVersion: { dashboard: '7.1.1', space: '6.6.6', }
 

docs/development/core/server/kibana-plugin-server.md

@@ -51,7 +51,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [PluginsServiceStart](./kibana-plugin-server.pluginsservicestart.md) |  |
 |  [RouteConfigOptions](./kibana-plugin-server.routeconfigoptions.md) | Route specific configuration. |
 |  [SavedObject](./kibana-plugin-server.savedobject.md) |  |
-|  [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) |  |
+|  [SavedObjectAttributes](./kibana-plugin-server.savedobjectattributes.md) | The data for a Saved Object is stored in the <code>attributes</code> key as either an object or an array of objects. |
 |  [SavedObjectReference](./kibana-plugin-server.savedobjectreference.md) | A reference to another saved object. |
 |  [SavedObjectsBaseOptions](./kibana-plugin-server.savedobjectsbaseoptions.md) |  |
 |  [SavedObjectsBulkCreateObject](./kibana-plugin-server.savedobjectsbulkcreateobject.md) |  |

docs/development/core/server/kibana-plugin-server.savedobject.attributes.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.attributes property
 
+The data for a Saved Object is stored in the `attributes` key as either an object or an array of objects.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.id.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.id property
 
+The ID of this Saved Object, guaranteed to be unique for all objects of the same `type`
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.md

@@ -15,12 +15,12 @@ export interface SavedObject<T extends SavedObjectAttributes = any>
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [attributes](./kibana-plugin-server.savedobject.attributes.md) | <code>T</code> |  |
+|  [attributes](./kibana-plugin-server.savedobject.attributes.md) | <code>T</code> | The data for a Saved Object is stored in the <code>attributes</code> key as either an object or an array of objects. |
 |  [error](./kibana-plugin-server.savedobject.error.md) | <code>{</code><br/><code>        message: string;</code><br/><code>        statusCode: number;</code><br/><code>    }</code> |  |
-|  [id](./kibana-plugin-server.savedobject.id.md) | <code>string</code> |  |
-|  [migrationVersion](./kibana-plugin-server.savedobject.migrationversion.md) | <code>SavedObjectsMigrationVersion</code> |  |
-|  [references](./kibana-plugin-server.savedobject.references.md) | <code>SavedObjectReference[]</code> |  |
-|  [type](./kibana-plugin-server.savedobject.type.md) | <code>string</code> |  |
-|  [updated\_at](./kibana-plugin-server.savedobject.updated_at.md) | <code>string</code> |  |
-|  [version](./kibana-plugin-server.savedobject.version.md) | <code>string</code> |  |
+|  [id](./kibana-plugin-server.savedobject.id.md) | <code>string</code> | The ID of this Saved Object, guaranteed to be unique for all objects of the same <code>type</code> |
+|  [migrationVersion](./kibana-plugin-server.savedobject.migrationversion.md) | <code>SavedObjectsMigrationVersion</code> | Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value. |
+|  [references](./kibana-plugin-server.savedobject.references.md) | <code>SavedObjectReference[]</code> | A reference to another saved object. |
+|  [type](./kibana-plugin-server.savedobject.type.md) | <code>string</code> | The type of Saved Object. Each plugin can define it's own custom Saved Object types. |
+|  [updated\_at](./kibana-plugin-server.savedobject.updated_at.md) | <code>string</code> | Timestamp of the last time this document had been updated. |
+|  [version](./kibana-plugin-server.savedobject.version.md) | <code>string</code> | An opaque version number which changes on each successful write operation. Can be used for implementing optimistic concurrency control. |
 

docs/development/core/server/kibana-plugin-server.savedobject.migrationversion.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.migrationVersion property
 
+Information about the migrations that have been applied to this SavedObject. When Kibana starts up, KibanaMigrator detects outdated documents and migrates them based on this value. For each migration that has been applied, the plugin's name is used as a key and the latest migration version as the value.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.references.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.references property
 
+A reference to another saved object.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.type.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.type property
 
+The type of Saved Object. Each plugin can define it's own custom Saved Object types.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.updated_at.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.updated\_at property
 
+Timestamp of the last time this document had been updated.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobject.version.md

@@ -4,6 +4,8 @@
 
 ## SavedObject.version property
 
+An opaque version number which changes on each successful write operation. Can be used for implementing optimistic concurrency control.
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobjectattributes.md

@@ -4,6 +4,7 @@
 
 ## SavedObjectAttributes interface
 
+The data for a Saved Object is stored in the `attributes` key as either an object or an array of objects.
 
 <b>Signature:</b>
 

docs/development/core/server/kibana-plugin-server.savedobjectsfindoptions.fields.md

@@ -4,8 +4,15 @@
 
 ## SavedObjectsFindOptions.fields property
 
+An array of fields to include in the results
+
 <b>Signature:</b>
 
 ```typescript
 fields?: string[];
 ```
+
+## Example
+
+SavedObjects.find(<!-- -->{<!-- -->type: 'dashboard', fields: \['attributes.name', 'attributes.location'\]<!-- -->}<!-- -->)
+

docs/development/core/server/kibana-plugin-server.savedobjectsfindoptions.md

@@ -16,12 +16,12 @@ export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [defaultSearchOperator](./kibana-plugin-server.savedobjectsfindoptions.defaultsearchoperator.md) | <code>'AND' &#124; 'OR'</code> |  |
-|  [fields](./kibana-plugin-server.savedobjectsfindoptions.fields.md) | <code>string[]</code> |  |
+|  [fields](./kibana-plugin-server.savedobjectsfindoptions.fields.md) | <code>string[]</code> | An array of fields to include in the results |
 |  [hasReference](./kibana-plugin-server.savedobjectsfindoptions.hasreference.md) | <code>{</code><br/><code>        type: string;</code><br/><code>        id: string;</code><br/><code>    }</code> |  |
 |  [page](./kibana-plugin-server.savedobjectsfindoptions.page.md) | <code>number</code> |  |
 |  [perPage](./kibana-plugin-server.savedobjectsfindoptions.perpage.md) | <code>number</code> |  |
-|  [search](./kibana-plugin-server.savedobjectsfindoptions.search.md) | <code>string</code> |  |
-|  [searchFields](./kibana-plugin-server.savedobjectsfindoptions.searchfields.md) | <code>string[]</code> | see Elasticsearch Simple Query String Query field argument for more information |
+|  [search](./kibana-plugin-server.savedobjectsfindoptions.search.md) | <code>string</code> | Search documents using the Elasticsearch Simple Query String syntax. See Elasticsearch Simple Query String <code>query</code> argument for more information |
+|  [searchFields](./kibana-plugin-server.savedobjectsfindoptions.searchfields.md) | <code>string[]</code> | The fields to perform the parsed query against. See Elasticsearch Simple Query String <code>fields</code> argument for more information |
 |  [sortField](./kibana-plugin-server.savedobjectsfindoptions.sortfield.md) | <code>string</code> |  |
 |  [sortOrder](./kibana-plugin-server.savedobjectsfindoptions.sortorder.md) | <code>string</code> |  |
 |  [type](./kibana-plugin-server.savedobjectsfindoptions.type.md) | <code>string &#124; string[]</code> |  |

docs/development/core/server/kibana-plugin-server.savedobjectsfindoptions.search.md

@@ -4,6 +4,8 @@
 
 ## SavedObjectsFindOptions.search property
 
+Search documents using the Elasticsearch Simple Query String syntax. See Elasticsearch Simple Query String `query` argument for more information
+
 <b>Signature:</b>
 
 ```typescript

docs/development/core/server/kibana-plugin-server.savedobjectsfindoptions.searchfields.md

@@ -4,7 +4,7 @@
 
 ## SavedObjectsFindOptions.searchFields property
 
-see Elasticsearch Simple Query String Query field argument for more information
+The fields to perform the parsed query against. See Elasticsearch Simple Query String `fields` argument for more information
 
 <b>Signature:</b>
 

docs/development/core/server/kibana-plugin-server.savedobjectsmigrationversion.md

@@ -14,12 +14,5 @@ export interface SavedObjectsMigrationVersion
 
 ## Example
 
-
-```
-migrationVersion: {
-  dashboard: '7.1.1',
-  space: '6.6.6',
-}
-
-```
+migrationVersion: { dashboard: '7.1.1', space: '6.6.6', }
 

src/core/public/public.api.md

@@ -578,31 +578,24 @@ export type RecursiveReadonly<T> = T extends (...args: any[]) => any ? T : T ext
 
 // @public (undocumented)
 export interface SavedObject<T extends SavedObjectAttributes = any> {
-    // (undocumented)
     attributes: T;
     // (undocumented)
     error?: {
         message: string;
         statusCode: number;
     };
-    // (undocumented)
     id: string;
-    // (undocumented)
     migrationVersion?: SavedObjectsMigrationVersion;
-    // (undocumented)
     references: SavedObjectReference[];
-    // (undocumented)
     type: string;
-    // (undocumented)
     updated_at?: string;
-    // (undocumented)
     version?: string;
 }
 
 // @public (undocumented)
 export type SavedObjectAttribute = string | number | boolean | null | undefined | SavedObjectAttributes | SavedObjectAttributes[];
 
-// @public (undocumented)
+// @public
 export interface SavedObjectAttributes {
     // (undocumented)
     [key: string]: SavedObjectAttribute | SavedObjectAttribute[];
@@ -674,7 +667,6 @@ export interface SavedObjectsCreateOptions {
 export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions {
     // (undocumented)
     defaultSearchOperator?: 'AND' | 'OR';
-    // (undocumented)
     fields?: string[];
     // (undocumented)
     hasReference?: {
@@ -685,7 +677,6 @@ export interface SavedObjectsFindOptions extends SavedObjectsBaseOptions {
     page?: number;
     // (undocumented)
     perPage?: number;
-    // (undocumented)
     search?: string;
     searchFields?: string[];
     // (undocumented)