Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve TSDocs for Core services #39693

Closed
5 of 14 tasks
joshdover opened this issue Jun 26, 2019 · 3 comments
Closed
5 of 14 tasks

Improve TSDocs for Core services #39693

joshdover opened this issue Jun 26, 2019 · 3 comments
Assignees
Labels
dev Feature:New Platform Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc

Comments

@joshdover
Copy link
Contributor

joshdover commented Jun 26, 2019

All services exposed via the public and server PluginInitializerContext, CoreSetup, and CoreStart need to have comprehensive TSDocs in order to make our generated markdown docs useful.

At a minimum, each top-level service should include:

  1. What the services is responsible for and what situations should it be used in.
  2. Examples of how to use the different methods of the service together.
  3. Descriptions on each function or value exposed by the service that explains what it does.
/**
 * ChromeStart allows plugins to customize the global chrome header UI and
 * enrich the UX with additional information about the current location of the
 * browser.
 *
 * @remarks
 * While ChromeStart exposes many APIs, they should be used sparingly and the
 * developer should understand how they affect other plugins and applications.
 *
 * @example
 * How to add a recently accessed item to the sidebar:
 * ```ts
 * core.chrome.recentlyAccessed.add('/app/map/1234', 'Map 1234', '1234');
 * ```
 *
 * @example
 * How to set the help dropdown extension:
 * ```tsx
 * core.chrome.setHelpExtension(elem => {
 *   ReactDOM.render(<MyHelpComponent />, elem);
 *   return () => ReactDOM.unmountComponentAtNode(elem);
 * });
 * ```
 *
 * @public
 */

Services that need improvement

Public APIs

  • HttpSetup
  • NotificationsSetup
  • UiSettingsSetup
  • ApplicationStart (@joshdover)
  • ChromeStart (@joshdover)
  • DocLinksStart
  • HttpStart
  • I18nStart - this service needs to change, probably not worth doing now
  • OverlaysStart
  • UISettingsStart

Server APIs

  • CoreSetup.elasticsearch
  • CoreSetup.http
  • SavedObjects
    • How references work / what they do
@joshdover joshdover added dev Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc Feature:New Platform labels Jun 26, 2019
@elasticmachine
Copy link
Contributor

Pinging @elastic/kibana-platform

@joshdover joshdover self-assigned this Sep 11, 2019
@joshdover
Copy link
Contributor Author

I'll be doing an audit here and creating issues for any services that still need additional docs.

@joshdover
Copy link
Contributor Author

Fixed by #47069

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dev Feature:New Platform Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc
Projects
None yet
Development

No branches or pull requests

2 participants