Documentation: Generate Docs for the data module #7264

youknowriad · 2018-06-11T14:34:29Z

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.

Soean · 2018-06-11T22:03:05Z

docs/data/tool/parser.js

+						node.type === 'ExportNamedDeclaration' &&
+						node.declaration.type === 'FunctionDeclaration' &&
+						node.leadingComments &&
+						node.leadingComments.lenght !== 0


tofumatt · 2018-06-12T11:04:33Z

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

tofumatt

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. 👍

tofumatt · 2018-06-12T11:06:34Z

docs/data/core-blocks.md

+
+### getBlockType
+
+Returns a block type by name.


"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.

tofumatt · 2018-06-12T11:14:22Z

docs/data/core-blocks.md

+
+### getCategories
+
+Returns all the available categories.


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.

tofumatt · 2018-06-12T11:15:14Z

docs/data/core-blocks.md

+
+*Parameters*
+
+ * state: Data state.


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.

tofumatt · 2018-06-12T11:16:08Z

docs/data/core-blocks.md

+
+### getDefaultBlockName
+
+Returns the name of the default block name.


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.

tofumatt · 2018-06-12T11:17:32Z

docs/data/core-blocks.md

+
+### getFallbackBlockName
+
+Returns the name of the fallback block name.


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.

tofumatt · 2018-06-12T11:42:34Z

docs/data/core-edit-post.md

+
+*Returns*
+
+Whether the editor sidebar is opened.


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

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.

tofumatt · 2018-06-12T11:43:57Z

docs/data/core-edit-post.md

+
+*Returns*
+
+Whether the plugin sidebar is opened.


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?

tofumatt · 2018-06-12T11:44:32Z

docs/data/core-edit-post.md

+
+### getPreference
+
+


All the empty newlines should be cleaned up.

tofumatt · 2018-06-12T11:44:53Z

docs/data/core-edit-post.md

+
+*Returns*
+
+Preferences Object.


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

tofumatt · 2018-06-12T11:46:09Z

docs/data/core-edit-post.md

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


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 · 2018-06-12T12:33:33Z

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 · 2018-06-12T13:05:25Z

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

aduth · 2018-06-12T13:25:40Z

docs/data/tool/parser.js

+				const code = fs.readFileSync( file, 'utf8' );
+				const parsedCode = espree.parse( code, {
+					attachComment: true,
+					ecmaVersion: 9,


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

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 · 2018-06-12T17:26:55Z

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 👍

tofumatt

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

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

tofumatt · 2018-06-19T11:33:40Z

docs/data/tool/config.js

+	namespaces: {
+		core: {
+			title: 'WordPress Core Data',
+			// Figures out a way to generate docs for the dynamic actions/selectors


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.

tofumatt · 2018-06-19T11:34:01Z

docs/data/tool/config.js

+			actions: [ path.resolve( root, 'blocks/store/actions.js' ) ],
+		},
+		'core/editor': {
+			title: 'The Editor\'s Data',


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

It looks like this is how things are set up.

Filed #7366, then 😄

tofumatt · 2018-06-19T11:34:43Z

docs/data/tool/config.js

+			actions: [ path.resolve( root, 'viewport/store/actions.js' ) ],
+		},
+		'core/nux': {
+			title: 'The NUX module Data',


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. 😄

tofumatt · 2018-06-19T11:36:15Z

docs/data/tool/generator.js

+	].join( '\n' );
+}
+
+module.exports = function( parsed, rootFolder ) {


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

tofumatt · 2018-06-19T11:38:21Z

docs/data/tool/parser.js

+				const code = fs.readFileSync( file, 'utf8' );
+				const parsedCode = espree.parse( code, {
+					attachComment: true,
+					ecmaVersion: 9,


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 · 2018-06-19T11:39:30Z

package.json

@@ -171,6 +173,7 @@
 		"test-unit:coverage-ci": "npm run test-unit -- --coverage --maxWorkers 1 && codecov",
 		"test-unit:watch": "npm run test-unit -- --watch",
 		"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"


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.

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

gziolo · 2018-06-19T11:53:57Z

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 :)

aduth · 2018-09-10T15:33:08Z

docs/data/tool/parser.js

+				parsedCode.body.forEach( ( node ) => {
+					if (
+						node.type === 'ExportNamedDeclaration' &&
+						node.declaration.type === 'FunctionDeclaration' &&


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

youknowriad added the [Type] Developer Documentation Documentation for developers label Jun 11, 2018

youknowriad self-assigned this Jun 11, 2018

youknowriad requested a review from a team June 11, 2018 14:34

youknowriad force-pushed the add/automate-data-module-docs branch 2 times, most recently from bbf8b85 to 99b67e1 Compare June 11, 2018 14:36

Soean reviewed Jun 11, 2018

View reviewed changes

Documentation: Generate Docs for the data module

ec3fbbd

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

tofumatt requested changes Jun 12, 2018

View reviewed changes

Remove useless empty lines

973a0b5

youknowriad mentioned this pull request Jun 12, 2018

Data Module: Improve Selectors/Actions docs #7287

Closed

aduth reviewed Jun 12, 2018

View reviewed changes

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

tofumatt approved these changes Jun 19, 2018

View reviewed changes

Address @tofumatt review comments

6d465a5

youknowriad force-pushed the add/automate-data-module-docs branch from 5838993 to 6d465a5 Compare June 19, 2018 12:26

youknowriad merged commit 3bbb260 into master Jun 19, 2018

youknowriad deleted the add/automate-data-module-docs branch June 19, 2018 12:46

youknowriad added this to the 3.1 milestone Jun 19, 2018

gziolo mentioned this pull request Jul 30, 2018

Documentation: Add "components" doc #4952

Closed

aduth reviewed Sep 10, 2018

View reviewed changes

aduth mentioned this pull request Sep 10, 2018

Tooling: Improve docs build to consider memoized selectors #9756

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation: Generate Docs for the data module #7264

Documentation: Generate Docs for the data module #7264

youknowriad commented Jun 11, 2018

Soean Jun 11, 2018

tofumatt commented Jun 12, 2018

tofumatt left a comment

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

aduth Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

tofumatt Jun 12, 2018

youknowriad commented Jun 12, 2018

youknowriad commented Jun 12, 2018

aduth Jun 12, 2018

tofumatt Jun 19, 2018

tofumatt commented Jun 12, 2018

tofumatt left a comment

tofumatt Jun 19, 2018

tofumatt Jun 19, 2018

gziolo Jun 19, 2018

tofumatt Jun 19, 2018

tofumatt Jun 19, 2018

tofumatt Jun 19, 2018

tofumatt Jun 19, 2018

tofumatt Jun 19, 2018

gziolo Jun 19, 2018

gziolo commented Jun 19, 2018

aduth Sep 10, 2018


		### getDefaultBlockName

		Returns the name of the default block name.


		### getFallbackBlockName

		Returns the name of the fallback block name.


		### initializeMetaBoxState

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


		Returns

		Preferences Object.

Documentation: Generate Docs for the data module #7264

Documentation: Generate Docs for the data module #7264

Conversation

youknowriad commented Jun 11, 2018

Choose a reason for hiding this comment

tofumatt commented Jun 12, 2018

tofumatt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad commented Jun 12, 2018

youknowriad commented Jun 12, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tofumatt commented Jun 12, 2018

tofumatt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Jun 19, 2018

Choose a reason for hiding this comment