From de9ab899caacb5e793fc09e9e22f319f197e4b2e Mon Sep 17 00:00:00 2001 From: Copons Date: Tue, 22 Oct 2019 13:46:12 +0100 Subject: [PATCH 1/2] Fix settings default section in Block Editor readme --- packages/block-editor/src/store/defaults.js | 47 +++++++++++---------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/packages/block-editor/src/store/defaults.js b/packages/block-editor/src/store/defaults.js index a983abacc36b8..e8dce69310fa9 100644 --- a/packages/block-editor/src/store/defaults.js +++ b/packages/block-editor/src/store/defaults.js @@ -10,29 +10,30 @@ export const PREFERENCES_DEFAULTS = { /** * The default editor settings * - * alignWide boolean Enable/Disable Wide/Full Alignments - * availableLegacyWidgets Array Array of objects representing the legacy widgets available. - * colors Array Palette colors - * disableCustomColors boolean Whether or not the custom colors are disabled - * fontSizes Array Available font sizes - * disableCustomFontSizes boolean Whether or not the custom font sizes are disabled - * imageSizes Array Available image sizes - * maxWidth number Max width to constraint resizing - * allowedBlockTypes boolean|Array Allowed block types - * hasFixedToolbar boolean Whether or not the editor toolbar is fixed - * hasPermissionsToManageWidgets boolean Whether or not the user is able to manage widgets. - * focusMode boolean Whether the focus mode is enabled or not - * styles Array Editor Styles - * isRTL boolean Whether the editor is in RTL mode - * bodyPlaceholder string Empty post placeholder - * titlePlaceholder string Empty title placeholder - * codeEditingEnabled string Whether or not the user can switch to the code editor - * showInserterHelpPanel boolean Whether or not the inserter help panel is shown - * __experimentalCanUserUseUnfilteredHTML string Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. - * __experimentalEnableLegacyWidgetBlock boolean Whether the user has enabled the Legacy Widget Block - * __experimentalEnableMenuBlock boolean Whether the user has enabled the Menu Block - * __experimentalBlockDirectory boolean Whether the user has enabled the Block Directory - * __experimentalEnableFullSiteEditing boolean Whether the user has enabled Full Site Editing + * @typedef {Object} SETTINGS_DEFAULT + * @property {boolean} alignWide Enable/Disable Wide/Full Alignments + * @property {Array} availableLegacyWidgets Array of objects representing the legacy widgets available. + * @property {Array} colors Palette colors + * @property {boolean} disableCustomColors Whether or not the custom colors are disabled + * @property {Array} fontSizes Available font sizes + * @property {boolean} disableCustomFontSizes Whether or not the custom font sizes are disabled + * @property {Array} imageSizes Available image sizes + * @property {number} maxWidth Max width to constraint resizing + * @property {boolean|Array} allowedBlockTypes Allowed block types + * @property {boolean} hasFixedToolbar Whether or not the editor toolbar is fixed + * @property {boolean} hasPermissionsToManageWidgets Whether or not the user is able to manage widgets. + * @property {boolean} focusMode Whether the focus mode is enabled or not + * @property {Array} styles Editor Styles + * @property {boolean} isRTL Whether the editor is in RTL mode + * @property {string} bodyPlaceholder Empty post placeholder + * @property {string} titlePlaceholder Empty title placeholder + * @property {boolean} codeEditingEnabled Whether or not the user can switch to the code editor + * @property {boolean} showInserterHelpPanel Whether or not the inserter help panel is shown + * @property {boolean} __experimentalCanUserUseUnfilteredHTML Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. + * @property {boolean} __experimentalEnableLegacyWidgetBlock Whether the user has enabled the Legacy Widget Block + * @property {boolean} __experimentalEnableMenuBlock Whether the user has enabled the Menu Block + * @property {boolean} __experimentalBlockDirectory Whether the user has enabled the Block Directory + * @property {boolean} __experimentalEnableFullSiteEditing Whether the user has enabled Full Site Editing */ export const SETTINGS_DEFAULTS = { alignWide: false, From 66b3f94bed69a1a54348886381dee330f075e845 Mon Sep 17 00:00:00 2001 From: Copons Date: Thu, 24 Oct 2019 16:42:28 +0100 Subject: [PATCH 2/2] Add typedef and property to the docgen formatter --- .../developers/data/data-core-block-editor.md | 17 ++++++ packages/block-editor/README.md | 52 +++++++++++-------- packages/docgen/src/markdown/formatter.js | 12 +++++ 3 files changed, 58 insertions(+), 23 deletions(-) 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 6f654f23e1609..b536c35738603 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -347,6 +347,23 @@ _Returns_ - `Array`: Items that appear in inserter. +_Type Definition_ + +- _WPEditorInserterItem_ `Object` + +_Properties_ + +- _id_ `string`: Unique identifier for the item. +- _name_ `string`: The type of block to create. +- _initialAttributes_ `Object`: Attributes to pass to the newly created block. +- _title_ `string`: Title of the item, as it appears in the inserter. +- _icon_ `string`: Dashicon for the item, as it appears in the inserter. +- _category_ `string`: Block category that the item is associated with. +- _keywords_ `Array`: Keywords that can be searched to find this item. +- _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item. +- _utility_ `number`: How useful we think this item is, between 0 and 3. +- _frecency_ `number`: Hueristic that combines frequency and recency. + # **getLastMultiSelectedBlockClientId** Returns the client ID of the last block in the multi-selection set, or null diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index a3f84683e02af..a758613c0ba36 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -374,29 +374,35 @@ Undocumented declaration. The default editor settings - alignWide boolean Enable/Disable Wide/Full Alignments - availableLegacyWidgets Array Array of objects representing the legacy widgets available. - colors Array Palette colors - disableCustomColors boolean Whether or not the custom colors are disabled - fontSizes Array Available font sizes - disableCustomFontSizes boolean Whether or not the custom font sizes are disabled - imageSizes Array Available image sizes - maxWidth number Max width to constraint resizing - allowedBlockTypes boolean|Array Allowed block types - hasFixedToolbar boolean Whether or not the editor toolbar is fixed - hasPermissionsToManageWidgets boolean Whether or not the user is able to manage widgets. - focusMode boolean Whether the focus mode is enabled or not - styles Array Editor Styles - isRTL boolean Whether the editor is in RTL mode - bodyPlaceholder string Empty post placeholder - titlePlaceholder string Empty title placeholder - codeEditingEnabled string Whether or not the user can switch to the code editor - showInserterHelpPanel boolean Whether or not the inserter help panel is shown - **experimentalCanUserUseUnfilteredHTML string Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. - **experimentalEnableLegacyWidgetBlock boolean Whether the user has enabled the Legacy Widget Block - **experimentalEnableMenuBlock boolean Whether the user has enabled the Menu Block - **experimentalBlockDirectory boolean Whether the user has enabled the Block Directory - \_\_experimentalEnableFullSiteEditing boolean Whether the user has enabled Full Site Editing +_Type Definition_ + +- _SETTINGS_DEFAULT_ `Object` + +_Properties_ + +- _alignWide_ `boolean`: Enable/Disable Wide/Full Alignments +- _availableLegacyWidgets_ `Array`: Array of objects representing the legacy widgets available. +- _colors_ `Array`: Palette colors +- _disableCustomColors_ `boolean`: Whether or not the custom colors are disabled +- _fontSizes_ `Array`: Available font sizes +- _disableCustomFontSizes_ `boolean`: Whether or not the custom font sizes are disabled +- _imageSizes_ `Array`: Available image sizes +- _maxWidth_ `number`: Max width to constraint resizing +- _allowedBlockTypes_ `(boolean|Array)`: Allowed block types +- _hasFixedToolbar_ `boolean`: Whether or not the editor toolbar is fixed +- _hasPermissionsToManageWidgets_ `boolean`: Whether or not the user is able to manage widgets. +- _focusMode_ `boolean`: Whether the focus mode is enabled or not +- _styles_ `Array`: Editor Styles +- _isRTL_ `boolean`: Whether the editor is in RTL mode +- _bodyPlaceholder_ `string`: Empty post placeholder +- _titlePlaceholder_ `string`: Empty title placeholder +- _codeEditingEnabled_ `boolean`: Whether or not the user can switch to the code editor +- _showInserterHelpPanel_ `boolean`: Whether or not the inserter help panel is shown +- _\_\_experimentalCanUserUseUnfilteredHTML_ `boolean`: Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. +- _\_\_experimentalEnableLegacyWidgetBlock_ `boolean`: Whether the user has enabled the Legacy Widget Block +- _\_\_experimentalEnableMenuBlock_ `boolean`: Whether the user has enabled the Menu Block +- _\_\_experimentalBlockDirectory_ `boolean`: Whether the user has enabled the Block Directory +- _\_\_experimentalEnableFullSiteEditing_ `boolean`: Whether the user has enabled Full Site Editing # **SkipToSelectedBlock** diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js index eaec51925f306..2c99ad002ed9e 100644 --- a/packages/docgen/src/markdown/formatter.js +++ b/packages/docgen/src/markdown/formatter.js @@ -109,6 +109,18 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart ( tag ) => `\n- \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, docs ); + formatTag( + 'Type Definition', + getSymbolTagsByName( symbol, 'typedef' ), + ( tag ) => `\n- *${ tag.name }* \`${ tag.type }\``, + docs + ); + formatTag( + 'Properties', + getSymbolTagsByName( symbol, 'property' ), + ( tag ) => `\n- *${ tag.name }* \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, + docs + ); docs.push( '\n' ); docs.push( '\n' ); } );