From d719a44b1018da0e9a4ddd462be666188557562a Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Fri, 26 Apr 2019 11:13:25 -0400 Subject: [PATCH] Documentation: Update docs tool to omit private, experimental, unstable APIs (#15188) * Documentation: Update docs tool to omit private selectors, actions * Documentation: Update docs tool to omit experimental, unstable APIs --- .../developers/data/data-core-annotations.md | 86 --------- .../developers/data/data-core-block-editor.md | 30 +-- .../developers/data/data-core-editor.md | 176 ------------------ docs/tool/parser.js | 79 +++++++- 4 files changed, 71 insertions(+), 300 deletions(-) diff --git a/docs/designers-developers/developers/data/data-core-annotations.md b/docs/designers-developers/developers/data/data-core-annotations.md index 6600938219e0e..0aaf9963ba48a 100644 --- a/docs/designers-developers/developers/data/data-core-annotations.md +++ b/docs/designers-developers/developers/data/data-core-annotations.md @@ -2,93 +2,7 @@ ## Selectors -### __experimentalGetAnnotationsForBlock -Returns the annotations for a specific client ID. - -*Parameters* - - * state: Editor state. - * clientId: The ID of the block to get the annotations for. - -### __experimentalGetAnnotationsForRichText - -Returns the annotations that apply to the given RichText instance. - -Both a blockClientId and a richTextIdentifier are required. This is because -a block might have multiple `RichText` components. This does mean that every -block needs to implement annotations itself. - -*Parameters* - - * state: Editor state. - * blockClientId: The client ID for the block. - * richTextIdentifier: Unique identifier that identifies the given RichText. - -*Returns* - -All the annotations relevant for the `RichText`. - -### __experimentalGetAnnotations - -Returns all annotations in the editor state. - -*Parameters* - - * state: Editor state. - -*Returns* - -All annotations currently applied. ## Actions -### __experimentalAddAnnotation - -Adds an annotation to a block. - -The `block` attribute refers to a block ID that needs to be annotated. -`isBlockAnnotation` controls whether or not the annotation is a block -annotation. The `source` is the source of the annotation, this will be used -to identity groups of annotations. - -The `range` property is only relevant if the selector is 'range'. - -*Parameters* - - * annotation: The annotation to add. - * blockClientId: The blockClientId to add the annotation to. - * richTextIdentifier: Identifier for the RichText instance the annotation applies to. - * range: The range at which to apply this annotation. - * range.start: The offset where the annotation should start. - * range.end: The offset where the annotation should end. - * string: [selector="range"] The way to apply this annotation. - * string: [source="default"] The source that added the annotation. - * string: [id=uuid()] The ID the annotation should have. - Generates a UUID by default. - -### __experimentalRemoveAnnotation - -Removes an annotation with a specific ID. - -*Parameters* - - * annotationId: The annotation to remove. - -### __experimentalUpdateAnnotationRange - -Updates the range of an annotation. - -*Parameters* - - * annotationId: ID of the annotation to update. - * start: The start of the new range. - * end: The end of the new range. - -### __experimentalRemoveAnnotationsBySource - -Removes all annotations of a specific source. - -*Parameters* - - * source: The source to remove. \ No newline at end of file diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index e3771108df101..d152b4475f8b2 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -801,20 +801,6 @@ via its `onChange` callback, in addition to `onInput`. Whether the most recent block change was persistent. -### __unstableIsLastBlockChangeIgnored - -Returns true if the most recent block change is be considered ignored, or -false otherwise. An ignored change is one not to be committed by -BlockEditorProvider, neither via `onChange` nor `onInput`. - -*Parameters* - - * state: Block editor state. - -*Returns* - -Whether the most recent block change was ignored. - ## Actions ### resetBlocks @@ -1108,18 +1094,4 @@ Returns an action object used in signalling that the block editor settings have *Parameters* - * settings: Updated settings - -### __unstableSaveReusableBlock - -Returns an action object used in signalling that a temporary reusable blocks have been saved -in order to switch its temporary id with the real id. - -*Parameters* - - * id: Reusable block's id. - * updatedId: Updated block's id. - -### __unstableMarkLastChangeAsPersistent - -Returns an action object used in signalling that the last block change should be marked explicitely as persistent. \ No newline at end of file + * settings: Updated settings \ No newline at end of file diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md index 69059845b2ad9..8a770b01e3029 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/designers-developers/developers/data/data-core-editor.md @@ -496,58 +496,6 @@ before falling back to serialization of block state. Post content. -### __experimentalGetReusableBlock - -Returns the reusable block with the given ID. - -*Parameters* - - * state: Global application state. - * ref: The reusable block's ID. - -*Returns* - -The reusable block, or null if none exists. - -### __experimentalIsSavingReusableBlock - -Returns whether or not the reusable block with the given ID is being saved. - -*Parameters* - - * state: Global application state. - * ref: The reusable block's ID. - -*Returns* - -Whether or not the reusable block is being saved. - -### __experimentalIsFetchingReusableBlock - -Returns true if the reusable block with the given ID is being fetched, or -false otherwise. - -*Parameters* - - * state: Global application state. - * ref: The reusable block's ID. - -*Returns* - -Whether the reusable block is being fetched. - -### __experimentalGetReusableBlocks - -Returns an array of all reusable blocks. - -*Parameters* - - * state: Global application state. - -*Returns* - -An array of all reusable blocks. - ### getStateBeforeOptimisticTransaction Returns state object prior to a specified optimist transaction ID, or `null` @@ -723,18 +671,6 @@ Return the current block list. Block list. -### __unstableIsEditorReady - -Is the editor ready - -*Parameters* - - * state: null - -*Returns* - -is Ready. - ### getEditorSettings Returns the post editor settings. @@ -783,43 +719,6 @@ Deprecated since 5.6. Callers should use the `receiveAutosaves( postId, autosave * newAutosave: Autosave post object. -### __experimentalRequestPostUpdateStart - -Optimistic action for dispatching that a post update request has started. - -*Parameters* - - * options: null - -### __experimentalRequestPostUpdateSuccess - -Optimistic action for indicating that the request post update has completed -successfully. - -*Parameters* - - * data: The data for the action. - * data.previousPost: The previous post prior to update. - * data.post: The new post after update - * data.isRevision: Whether the post is a revision or not. - * data.options: Options passed through from the original - action dispatch. - * data.postType: The post type object. - -### __experimentalRequestPostUpdateFailure - -Optimistic action for indicating that the request post update has completed -with a failure. - -*Parameters* - - * data: The data for the action - * data.post: The post that failed updating. - * data.edits: The fields that were being updated. - * data.error: The error from the failed call. - * data.options: Options passed through from the original - action dispatch. - ### updatePost Returns an action object used in signalling that a patch of updates for the @@ -847,15 +746,6 @@ been edited. * edits: Post attributes to edit. -### __experimentalOptimisticUpdatePost - -Returns action object produced by the updatePost creator augmented by -an optimist option that signals optimistically applying updates. - -*Parameters* - - * edits: Updated post fields. - ### savePost Action generator for saving the current post in the editor. @@ -902,72 +792,6 @@ Returns an action object used to lock the editor. * lock: Details about the post lock status, user, and nonce. -### __experimentalFetchReusableBlocks - -Returns an action object used to fetch a single reusable block or all -reusable blocks from the REST API into the store. - -*Parameters* - - * id: If given, only a single reusable block with this ID will - be fetched. - -### __experimentalReceiveReusableBlocks - -Returns an action object used in signalling that reusable blocks have been -received. `results` is an array of objects containing: - - `reusableBlock` - Details about how the reusable block is persisted. - - `parsedBlock` - The original block. - -*Parameters* - - * results: Reusable blocks received. - -### __experimentalSaveReusableBlock - -Returns an action object used to save a reusable block that's in the store to -the REST API. - -*Parameters* - - * id: The ID of the reusable block to save. - -### __experimentalDeleteReusableBlock - -Returns an action object used to delete a reusable block via the REST API. - -*Parameters* - - * id: The ID of the reusable block to delete. - -### __experimentalUpdateReusableBlockTitle - -Returns an action object used in signalling that a reusable block's title is -to be updated. - -*Parameters* - - * id: The ID of the reusable block to update. - * title: The new title. - -### __experimentalConvertBlockToStatic - -Returns an action object used to convert a reusable block into a static -block. - -*Parameters* - - * clientId: The client ID of the block to attach. - -### __experimentalConvertBlockToReusable - -Returns an action object used to convert a static block into a reusable -block. - -*Parameters* - - * clientIds: The client IDs of the block to detach. - ### enablePublishSidebar Returns an action object used in signalling that the user has enabled the diff --git a/docs/tool/parser.js b/docs/tool/parser.js index 41b02c87bb314..25dc7e34d41f8 100644 --- a/docs/tool/parser.js +++ b/docs/tool/parser.js @@ -6,7 +6,7 @@ const fs = require( 'fs' ); /** * External dependencies */ -const { last, size, first } = require( 'lodash' ); +const { last, size, first, some, overEvery, negate, isEmpty } = require( 'lodash' ); const espree = require( 'espree' ); const doctrine = require( 'doctrine' ); @@ -25,6 +25,29 @@ function isDocumentedNamedExport( node ) { ); } +/** + * Returns true if the given exported declaration name is considered stable for + * documentation, or false otherwise. + * + * @see https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#experimental-and-unstable-apis + * + * @param {string} name Name to test. + * + * @return {boolean} Whether the provided name describes a stable API. + */ +const isStableExportName = ( name ) => ! /^__(unstable|experimental)/.test( name ); + +/** + * Returns true if the given export name is eligible to be included in + * generated output, or false otherwise. + * + * @type {boolean} Whether name is eligible for documenting. + */ +const isEligibleExportedName = overEvery( [ + negate( isEmpty ), + isStableExportName, +] ); + /** * Returns the assigned name for a given declaration node type, or undefined if * it cannot be determined. @@ -49,6 +72,37 @@ function getDeclarationExportedName( declaration ) { } } +/** + * Returns true if the given DocBlock contains at least one reference to the + * tag named by the provided title, or false otherwise. + * + * @param {Object} docBlock Parsed DocBlock node. + * @param {string} title Title to search. + * + * @return {boolean} Whether DocBlock contains tag by title. + */ +const hasDocBlockTag = ( docBlock, title ) => some( docBlock.tags, { title } ); + +/** + * Returns true if the given DocBlock contains at least one reference to a + * private tag. + * + * @param {Object} docBlock Parsed DocBlock node. + * + * @return {boolean} Whether DocBlock contains private tag. + */ +const hasPrivateTag = ( docBlock ) => hasDocBlockTag( docBlock, 'private' ); + +/** + * Returns true if the given DocBlock contains at least one reference to a + * param tag. + * + * @param {Object} docBlock Parsed DocBlock node. + * + * @return {boolean} Whether DocBlock contains param tag. + */ +const hasParamTag = ( docBlock ) => hasDocBlockTag( docBlock, 'param' ); + /** * Maps parse type to specific filtering logic by which to consider for * inclusion a parsed named export. @@ -57,18 +111,25 @@ function getDeclarationExportedName( declaration ) { */ const FILTER_PARSED_DOCBLOCK_BY_TYPE = { /** - * Selectors filter. Excludes documented exports which do not include at - * least one `@param` DocBlock tag. This is used to distinguish between - * selectors (which at least receive state as an argument) and exported - * constant values. + * Selectors filter. Excludes documented exports either marked as private + * or which do not include at least one `@param` DocBlock tag. This is used + * to distinguish between selectors (which at least receive state as an + * argument) and exported constant values. * * @param {Object} docBlock DocBlock object to test. * * @return {boolean} Whether documented selector should be included. */ - selectors( docBlock ) { - return !! docBlock.tags.some( ( tag ) => tag.title === 'param' ); - }, + selectors: overEvery( [ hasParamTag, negate( hasPrivateTag ) ] ), + + /** + * Actions filter. Excludes documented exports marked as private. + * + * @param {Object} docBlock DocBlock object to test. + * + * @return {boolean} Whether documented action should be included. + */ + actions: negate( hasPrivateTag ), }; module.exports = function( config ) { @@ -107,7 +168,7 @@ module.exports = function( config ) { } const name = getDeclarationExportedName( node.declaration ); - if ( ! name ) { + if ( ! isEligibleExportedName( name ) ) { return; }