Skip to content

Documentation: Generate Docs for the data module - #7264

Merged
youknowriad merged 3 commits into
masterfrom
add/automate-data-module-docs
Jun 19, 2018
Merged

youknowriad merged 3 commits into
masterfrom
add/automate-data-module-docs

Conversation

@youknowriad

Copy link
Copy Markdown
Contributor

This PR adds docs generation for the data module's selectors/actions.

  • The docs live in docs/data/*.md
  • To regenerate the docs, we run npm run docs:generate-data-reference
  • It doesn't support the dynamic selectors/actions from the core-data module.
  • The output is printed as markdown.

It doesn't integrate with the Handbook yet but it should be possible to add a step to call this command line before doing the synchronization cc @pento

Its output is markdown to ease integration into other docs systems like the handbook.

The docs can be gitignored at some point but I think it's fine to do the generation manually as a start.

@youknowriad youknowriad added the [Type] Developer Documentation Documentation for developers label Jun 11, 2018
@youknowriad youknowriad self-assigned this Jun 11, 2018
@youknowriad
youknowriad requested a review from a team June 11, 2018 14:34
@youknowriad
youknowriad force-pushed the add/automate-data-module-docs branch 2 times, most recently from bbf8b85 to 99b67e1 Compare June 11, 2018 14:36
Comment thread docs/data/tool/parser.js Outdated
node.type === 'ExportNamedDeclaration' &&
node.declaration.type === 'FunctionDeclaration' &&
node.leadingComments &&
node.leadingComments.lenght !== 0

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.length

@youknowriad
youknowriad force-pushed the add/automate-data-module-docs branch from 99b67e1 to ec3fbbd Compare June 12, 2018 08:22
@tofumatt

Copy link
Copy Markdown
Member

OMG yes ❤️ so much for this. I'll have a look through and see if they make sense to my relatively green self.

@tofumatt tofumatt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is great and there's some helpful stuff in here, but we should work to improve the signal-to-noise ratio of the docs and assume a lot less knowledge in them.

There are a lot of functions here whose name/name+parameters explain everything (or where if they don't, the docs are just re-stated function signatures.

I made some suggestions on particular docs but they apply throughout, really. If my suggestions make sense and can be extrapolated to the rest of the docs I'm happy to review again after a pass with my thoughts in mind.

If I need to clarify my general thoughts more/my criticisms are unclear just let me know 😄

This is an awesome effort and will be really handy for new devs when iterated upon. 👍

Comment thread docs/data/core-blocks.md

### getBlockType

Returns a block type by name.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"type by name" is a bit awkward, especially because "name" isn't really a type that I'd expect to provide clarification.

This might be better stated as "Return a block type as a string (eg. by name)." An example would be even better.

Comment thread docs/data/core-blocks.md

### getCategories

Returns all the available categories.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've noticed "returns" instead of "return" used everywhere here and I'm not sure it makes sense in prose. I guess it's not wrong per-se but it doesn't really add anything 😄

It makes sense as a header but not in prose to me. I guess I like "Return all available categories" over "Returns all the available categories" but maybe that's also my English-as-a-first-language creeping through; we leave out articles like "the" a lot I find.

Comment thread docs/data/core-blocks.md

*Parameters*

* state: Data state.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any way we can make this an include in Markdown? It's repeated a lot. "redux state" might also be a bit better to use as a descriptor as well, for what it's worth.

Comment thread docs/data/core-blocks.md

### getDefaultBlockName

Returns the name of the default block name.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The default block name in what context? I'm guessing it's for the editor context (and this is probably <p> by default), but that isn't clear from just reading the docs.

Comment thread docs/data/core-blocks.md

### getFallbackBlockName

Returns the name of the fallback block name.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A lot of these functions are somewhat clear based on their function names, so an explanation like this one doesn't really help, I think.

But the docs could really shine if this explained (not in detail, but even just in passing), what a fallback block was. Why you'd use this and what it's for would really help contextualise a lot of these selector functions.


*Returns*

Whether the editor sidebar is opened.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is what it does, but what it returns is `true` if sidebar is open; `false` if sidebar is not open.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is what it does, but what it returns is `true` if sidebar is open; `false` if sidebar is not open.

Aside: Typically the primary description would include a "true if ..., otherwise false". Also there is type information available in the JSDoc {boolean} we are not including here.


*Returns*

Whether the plugin sidebar is opened.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A lot of these have explanations that should be the return value and return values that better explain the function. Maybe it's worth switching them?

Comment thread docs/data/core-edit-post.md Outdated

### getPreference


Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the empty newlines should be cleaned up.


*Returns*

Preferences Object.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we link to this? Otherwise this isn't a helpful explainer.


### initializeMetaBoxState

Returns an action object used to check the state of meta boxes at a location.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an example of where the extra detail and explanation really helps. A lot of the docs around these selectors is stating the obvious or just re-stating their names and function method in a more verbose and manual way.

Maybe it's worth not adding redundant docs for a lot of them if it's very obvious.

@youknowriad

Copy link
Copy Markdown
Contributor Author

Thanks for the review @tofumatt Great feedback here.

I'd like to keep this PR focused on the docs generation aspect and not the descriptions/docs them selves. I'd like to tackle those comments in a separate PR (Probably worth creating an issue with a link to these comments).

The extra new lines is probably something related to the docs generation tool itself though.

@youknowriad

Copy link
Copy Markdown
Contributor Author

@tofumatt I created this issue to address these concerns about the descriptions etc... #7287 Feel free to update it

Comment thread docs/data/tool/parser.js
const code = fs.readFileSync( file, 'utf8' );
const parsedCode = espree.parse( code, {
attachComment: true,
ecmaVersion: 9,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The downside here is we're not strictly following the Babel configuration, which may only become an issue for more bleeding edge functionality.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a comment pointing that out would be good; even if just so we can grep for "Babel" later and see why the docs aren't using our Babel config? 🤷‍♂️

@tofumatt

Copy link
Copy Markdown
Member

So my bad, I didn't realise this was all generated; I should have realised with such a massive green line count 😆

Thanks for filing the issue related to the content of the documentation itself; for now my issues with this PR are just with nitpicks around the newlines and such 👍

@youknowriad
youknowriad requested a review from tofumatt June 19, 2018 09:06

@tofumatt tofumatt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r+wc (That's Mozilla-speak for approved-once-comments-are-addressed)

Code looks good and the generated documentation looks a bit cleaner too 👍

Comment thread docs/data/tool/config.js Outdated
namespaces: {
core: {
title: 'WordPress Core Data',
// Figures out a way to generate docs for the dynamic actions/selectors

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tense here implies that the following code "figures out a way" to do something, but I'm thinking this is actually a TODO, eg:

// TODO: Figure out a way to generate docs for dynamic actions/selectors

Sounds like something best filed as a "code quality" issue 😆, but I'd at least tidy up this comment so it isn't confusing.

Comment thread docs/data/tool/config.js
actions: [ path.resolve( root, 'blocks/store/actions.js' ) ],
},
'core/editor': {
title: 'The Editor\'s Data',

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the style guide not let us use double quotes rather than escaping? It's sooooo ugly.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this is how things are set up.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Filed #7366, then 😄

Comment thread docs/data/tool/config.js Outdated
actions: [ path.resolve( root, 'viewport/store/actions.js' ) ],
},
'core/nux': {
title: 'The NUX module Data',

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you wanted to add "(New User Experience)" after "NUX" that might be handy as readers of these docs could be less experienced with that acronym. 😄

Comment thread docs/data/tool/generator.js Outdated
].join( '\n' );
}

module.exports = function( parsed, rootFolder ) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

parsed what? I think it's parsedCode, right? Could we label it a bit better?

Comment thread docs/data/tool/parser.js
const code = fs.readFileSync( file, 'utf8' );
const parsedCode = espree.parse( code, {
attachComment: true,
ecmaVersion: 9,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a comment pointing that out would be good; even if just so we can grep for "Babel" later and see why the docs aren't using our Babel config? 🤷‍♂️

Comment thread package.json Outdated
"test-unit-php": "docker-compose run --rm wordpress_phpunit phpunit",
"test-unit-php-multisite": "docker-compose run -e WP_MULTISITE=1 --rm wordpress_phpunit phpunit"
"test-unit-php-multisite": "docker-compose run -e WP_MULTISITE=1 --rm wordpress_phpunit phpunit",
"docs:generate-data-reference": "node docs/data/tool"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you move this above, under the dev: commands? The rest of these commands are sorted alphabetically so that'll make them easier to scan.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I like to have things sorted alphabetically. It's much easier to find what you need.

@gziolo

gziolo commented Jun 19, 2018

Copy link
Copy Markdown
Member

Yes, let's move on with this one and iterate later. We should discuss it at Core JS chat together with @atimmer so we could align with the parallel efforts for the existing WordPress codebase: https://make.wordpress.org/core/2018/06/14/js-docs-initiative-add-inline-docs-for-javascript-part-2/.

By the way, @atimmer, your review is warmly welcomed :)

@youknowriad
youknowriad force-pushed the add/automate-data-module-docs branch from 5838993 to 6d465a5 Compare June 19, 2018 12:26
@youknowriad
youknowriad merged commit 3bbb260 into master Jun 19, 2018
@youknowriad
youknowriad deleted the add/automate-data-module-docs branch June 19, 2018 12:46
@youknowriad youknowriad added this to the 3.1 milestone Jun 19, 2018
Comment thread docs/data/tool/parser.js
parsedCode.body.forEach( ( node ) => {
if (
node.type === 'ExportNamedDeclaration' &&
node.declaration.type === 'FunctionDeclaration' &&

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI this excludes memoized selectors. See fix/improvement at #9756

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants