more doc

src/core/server/elasticsearch/client/client_config.ts

@@ -24,9 +24,8 @@ import { ClientOptions, NodeOptions } from '@elastic/elasticsearch';
 import { ElasticsearchConfig } from '../elasticsearch_config';
 
 /**
- * @privateRemarks Config that consumers can pass to the Elasticsearch JS client is complex and includes
- * not only entries from standard `elasticsearch.*` yaml config, but also some Elasticsearch JS
- * client specific options like `keepAlive` or `plugins` (that eventually will be deprecated).
+ * Configuration options to be used to create a {@link IClusterClient | cluster client} using the
+ * {@link ElasticsearchServiceStart.createClient | createClient API}
  *
  * @public
  */
@@ -48,6 +47,13 @@ export type ElasticsearchClientConfig = Pick<
   keepAlive?: boolean;
 };
 
+/**
+ * Parse the client options from given client config and `scoped` flag.
+ *
+ * @param config The config to generate the client options from.
+ * @param scoped if true, will adapt the configuration to be used by a scoped client
+ *        (will remove basic auth and ssl certificates)
+ */
 export function parseClientOptions(
   config: ElasticsearchClientConfig,
   scoped: boolean

src/core/server/elasticsearch/client/get_client_facade.ts

@@ -31,6 +31,8 @@ import { ClientFacade } from './client_facade';
  * @internal
  */
 export const getClientFacade = (client: Client, headers: Headers = {}): ClientFacade => {
+  // do not rename or change this method signature without adapting the API generation script
+  // at `src/dev/generate_es_client.ts`
   const addHeaders = (options?: TransportRequestOptions): TransportRequestOptions => {
     if (!options) {
       return {

src/core/server/elasticsearch/client/scoped_cluster_client.ts

@@ -19,9 +19,24 @@
 
 import { ClientFacade } from './client_facade';
 
-/** @public **/
+/**
+ * Serves the same purpose as the normal {@link ClusterClient | cluster client} but exposes
+ * an additional `asCurrentUser` method that doesn't use credentials of the Kibana internal
+ * user (as `asInternalUser` does) to request Elasticsearch API, but rather passes HTTP headers
+ * extracted from the current user request to the API instead.
+ *
+ * @public
+ **/
 export interface IScopedClusterClient {
+  /**
+   * Returns a {@link ClientFacade | client facade} to be used to query the elasticsearch cluster
+   * on behalf of the internal Kibana user.
+   */
   asInternalUser: () => ClientFacade;
+  /**
+   * Returns a {@link ClientFacade | client facade} to be used to query the elasticsearch cluster
+   * on behalf of the user that initiated the request to the Kibana server.
+   */
   asCurrentUser: () => ClientFacade;
 }