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

Jump to bottom

Docgen: Add @typedef and @property tags #18059

Merged
merged 2 commits into from Nov 14, 2019
Merged

Docgen: Add @typedef and @property tags #18059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de9ab89
Fix settings default section in Block Editor readme
Copons Oct 22, 2019
66b3f94
Add typedef and property to the docgen formatter
Copons Oct 24, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/designers-developers/developers/data/data-core-block-editor.md
View file
Open in desktop
Expand Up @@ -347,6 +347,23 @@ _Returns_

- `Array<WPEditorInserterItem>`: 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<string>`: 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.

<a name="getLastMultiSelectedBlockClientId" href="#getLastMultiSelectedBlockClientId">#</a> **getLastMultiSelectedBlockClientId**

Returns the client ID of the last block in the multi-selection set, or null
Expand Down
52 changes: 29 additions & 23 deletions packages/block-editor/README.md
View file
Open in desktop
Expand Up @@ -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

<a name="SkipToSelectedBlock" href="#SkipToSelectedBlock">#</a> **SkipToSelectedBlock**

Expand Down
47 changes: 24 additions & 23 deletions packages/block-editor/src/store/defaults.js
View file
Open in desktop
Expand Up @@ -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,
Expand Down
12 changes: 12 additions & 0 deletions packages/docgen/src/markdown/formatter.js
View file
Open in desktop
Expand Up @@ -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' );
} );
Expand Down