Enhancement: Improve Documentation #278

ahmadawais · 2017-03-15T18:39:46Z

This PR improves the internal documentation for index.php

…ui-prototype Prevent input for non-text selections

…ui-prototype Use functions instead of commands where appropriate

…tyle. Also make it keyboard friendly (WordPress#136) * update the TinyMCE per Block prototype UI to match the Prototype UI style * Adding heading block * Adding a paragraph block and moving to React - preact has some state updating bugs * Allowing removing/merging components using backspace * Handling navigation using arrow keys * Adding a simple quote block

…hs, quotes, headings) (WordPress#148)

- Includes a new drag and drop mockup - Includes an admin with the sidebar closed - Includes an updated Sketch file that has the admin UI stuff

Update Mockups

…ui-prototype Tinymce single/mimic ui prototype

…ui-prototype Hide inline formatting toolbar along with rest of block UI

…ui-prototype Tinymce single/mimic ui prototype

…ui-prototype Start work on inserter

…ui-prototype Add undo levels for moving blocks

…ui-prototype Lighter UI: only leave align centre, clearer remove format icons

…Press#269.

Note: It creates additional paragraphs when dragging non editable blocks. This reverts commit bef6be3.

@j-falk

These mockup updates include general refinements and polish, per Github and Slack discussions. Notably around: - Galleries. Props @j-falk for ideas here. Trash and edit buttons when selecting individual images in a gallery, and button for advanced gallery editing, where you'd also be able to add more images to the gallery, or rearrange, in the case of a slideshow version of the gallery. - Drag and drop. Props @iseulde for the idea of showing a blue line for the dropzone. The gray area is a ghost of where you're dragging from, so the blocks don't size around when you drag. - A new approach to inserting content. It generally happens on a newline, and the plus then shows up to the left, where the up/down arrows would show up for a non-empty block. We'd then have a permanent "insert" button somewhere in the Admin UI to go with this, for when you need to insert content between two letters. See also WordPress#78. - Added empty versions of Quote and Image block. Imagine the use case of _type type type, press enter for newline, type `/ima` to open inserter searched to Image, press enter, arrow down, type type type_. In that case you'd simply inserted an image placeholder block which you could later upload to, or pick an image from the media library.

Update mockups

Filenames with unencoded spaces worked yesterday. Suddenly it doesn't. No idea why. Will use dashes instead of spaces in the future.

Fix weirdly broken markdown

…ing the image)

Adding plugin folder for the project.

This PR improves the internal documentation for index.php

aduth · 2017-03-16T13:48:10Z

plugin/index.php

 /**
 * Plugin Name: Gutenberg
 * Plugin URI: https://wordpress.github.io/gutenberg/
 * Description: Prototyping since 1440. Development plugin for the editor focus in core.
 * Version: 0.1
 */
-
+// Hook.


My personal view is that a comment shouldn't exist to describe what exists, but why (more specifically in clarifying potentially ambiguous logic). In this case, "Hook" is already quite clear merely by the invoking add_action.

My intention of adding this comment is always to be liberal with documentation. It not only makes sense (to me) but helps the code look more clean.

My intention of adding this comment is always to be liberal with documentation.

There's an underlying assumption here that "more documentation is always better", to which my comment is primarily directed at disputing.

Are you suggesting that we should not document this? Do you have an alternate suggestion here?

Are you suggesting that we should not document this? Do you have an alternate suggestion here?

Right, it's fine to not have comments where comments aren't serving value.

aduth · 2017-03-16T13:49:06Z

plugin/index.php

+/**
+ * Gutenberg's Menu.
+ *
+ * @since  0.0.1


Do you think @since should follow the repository's own versioning, or that of what we expect the WordPress version to be upon integration? We may simply want to leave it out for future consideration.

Well, currently, I added it as per the repository's version but changing it to 4.8.0 does make more sense. Will go ahead and change it.

aduth · 2017-03-16T13:49:13Z

plugin/index.php

+/**
+ * Scripts & Styles.
+ *
+ * @param  [type]    $hook


[type] should be defined. There should also be a description explaining what $hook is.

It was not as clear to me, so I let it be to be reviewed and added at a later stage. I think the $hook is going to be a string value of screen name?

Just addressed this one.

aduth · 2017-03-16T13:51:47Z

plugin/index.php

@@ -19,13 +23,26 @@ function gutenberg_menu() {
 	);
 }

+// Hook.
+add_action( 'admin_enqueue_scripts', 'gutenberg_scripts_and_styles' );


I like that this was made consistent with positioning relative to its callback function with the one earlier in this file, but what's the pattern we should follow with regards to being above/below the function declaration? At least in twenty* themes and built-in plugins (hello.php), it's placed below the function.

It was an intentional decision. See this:

Having function and file level DocBlocks right after one and another makes less sense. That's why I kept the hooks at the top.

Having function and file level DocBlocks right after one and another makes less sense.

In what way does it make less sense?

The relative positioning doesn't really impact much since it works in either case. My point in bringing it up was in whether it may be at odds with expectations other contributors would have coming in being familiar with differing patterns found more commonly in other plugins and core code.

I am not sure if there is a pattern there. I myself follow both, but I remain consistent at least in one single project.

It makes lesser sense as two block level comments stacked together do NOT look good. That's the only reason why I do this.

Normally, I creat a function like this.

Here's a couple examples of the precedent I was referring to:

https://github.com/WordPress/WordPress/blob/9f4bbcd/wp-content/themes/twentyseventeen/functions.php#L530-L542

https://github.com/WordPress/WordPress/blob/dd6da70/wp-content/plugins/hello.php#L80

There's not a whole lot of examples in the core code itself, as callbacks are often defined separate from the hook itself or the hook is created in the constructor of a class.

Guess, that's what I ended up with on the merged PR>

aduth · 2017-03-16T13:53:55Z

Definitely good to be thinking about documenting functions. We should be striving to include these with any new code we introduce 👍

ahmadawais · 2017-03-17T02:46:58Z

Just addressed the conflicts. See if this is mergable now?

youknowriad · 2017-03-17T09:22:11Z

I think this needs to be rebased over the new master (to avoid keeping the old history)

ahmadawais · 2017-03-17T12:53:16Z

@youknowriad Should I add a new PR or rebase this one?

youknowriad · 2017-03-17T13:00:17Z

What works best for you. I'm not an expert Git, if you want to keep this one, maybe @nylen could help

ahmadawais · 2017-03-17T13:34:45Z

@aduth and @youknowriad I have closed this PR. Was going to rebase it but I think the plugin files have been moved since then? Do you know where?

youknowriad · 2017-03-17T13:45:47Z

yes, the root folder :)

ahmadawais · 2017-03-17T14:18:12Z

Damn, how did I miss that :P 👍

aduth · 2017-03-17T19:21:31Z

Sorry for the delay in responding. I'll add comments here, though understanding points have been reiterated and changes merged in #290.

ellatrix and others added 30 commits February 28, 2017 11:45

Prevent input for non-text selections

12c8c7c

Merge pull request WordPress#145 from WordPress/tinymce-single/mimic-…

8973a8e

…ui-prototype Prevent input for non-text selections

Use functions instead of commands where appropriate

824aa8a

Merge pull request WordPress#146 from WordPress/tinymce-single/mimic-…

b1d9b8f

…ui-prototype Use functions instead of commands where appropriate

Add some more content and blocks

5374d64

Restore link functionality

05a8686

Hide all UI on blur

195e130

Fix webkit range.getBoundingClientRect quirk

f8b4055

Per Block Prototype: Use an inline tinymce for small blocks (paragrap…

efc7d11

…hs, quotes, headings) (WordPress#148)

Update Mockups

1ef60a2

- Includes a new drag and drop mockup - Includes an admin with the sidebar closed - Includes an updated Sketch file that has the admin UI stuff

Merge pull request WordPress#151 from WordPress/update/mockups

4d1902a

Update Mockups

Emit nodechange on left text align too

f602d59

Show link toolbar on the bottom of selection

7e6d178

Move inline toolbar next to block toolbar

f687176

Merge pull request WordPress#152 from WordPress/tinymce-single/mimic-…

2641694

…ui-prototype Tinymce single/mimic ui prototype

Hide inline formatting toolbar along with rest of block UI

662d322

Merge pull request WordPress#154 from WordPress/tinymce-single/mimic-…

d3ba08a

…ui-prototype Hide inline formatting toolbar along with rest of block UI

Adding a quote with cite block (WordPress#153)

1110690

Add image with caption block (WordPress#155)

84507cb

Remove delete button, delete block on backspace correctly

ba408b7

Make sure focusnode is block before deleting whole block

88c8e70

Merge pull request WordPress#156 from WordPress/tinymce-single/mimic-…

f8c7b89

…ui-prototype Tinymce single/mimic ui prototype

Start work on inserter

2a68b10

Merge pull request WordPress#157 from WordPress/tinymce-single/mimic-…

de05f3f

…ui-prototype Start work on inserter

Add undo levels for moving blocks

8ab6e86

Merge pull request WordPress#159 from WordPress/tinymce-single/mimic-…

617f2ed

…ui-prototype Add undo levels for moving blocks

Lighter UI: only leave align centre, clearer remove format icons

4ed981a

Merge pull request WordPress#160 from WordPress/tinymce-single/mimic-…

908be1c

…ui-prototype Lighter UI: only leave align centre, clearer remove format icons

Remove block icon for now

8567ecb

ellatrix and others added 14 commits March 15, 2017 08:40

Only show UI on setSelectionRange for non editable blocks. Fixes Word…

719cc11

…Press#269.

Revert "Keep the selection on drop"

dcac834

Note: It creates additional paragraphs when dragging non editable blocks. This reverts commit bef6be3.

Merge pull request WordPress#270 from WordPress/add/mockups

0b7c5dd

Update mockups

Fix weirdly broken markdown

50caedd

Filenames with unencoded spaces worked yesterday. Suddenly it doesn't. No idea why. Will use dashes instead of spaces in the future.

Merge pull request WordPress#271 from WordPress/update/readme

0875e86

Fix weirdly broken markdown

Adjust custom enter behaviour

ab8117f

Only show inline UI on editable areas

f44503a

TinyMCE per block: Fix small remaining bugs (Format toolbar and focus…

abb8e40

…ing the image)

Single: Add type switcher to rest of text blocks

b20d813

Adding plugin folder for the project.

6aec48e

Merge pull request WordPress#276 from WordPress/add/plugin-folder

8d6ce23

Adding plugin folder for the project.

Single: type switching: reset the selection

d9c49d9

Enhancement: Improve Documentation

4c41fb2

This PR improves the internal documentation for index.php

jasmussen mentioned this pull request Mar 16, 2017

Initial plugin readme.md based on template from dd32 #281

Closed

aduth reviewed Mar 16, 2017

View reviewed changes

nylen force-pushed the master branch from 6e742ee to 77605ae Compare March 16, 2017 15:59

Merge branch 'master' into patch-4

31ee686

ahmadawais closed this Mar 17, 2017

ahmadawais deleted the patch-4 branch March 17, 2017 13:34

ahmadawais mentioned this pull request Mar 17, 2017

Enhancement: Improve Documentation & Yoda Condition #290

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhancement: Improve Documentation #278

Enhancement: Improve Documentation #278

ahmadawais commented Mar 15, 2017

aduth Mar 16, 2017

ahmadawais Mar 16, 2017

aduth Mar 16, 2017 •

edited

Loading

ahmadawais Mar 17, 2017

aduth Mar 17, 2017

aduth Mar 16, 2017

ahmadawais Mar 16, 2017

aduth Mar 16, 2017

ahmadawais Mar 16, 2017

ahmadawais Mar 17, 2017

aduth Mar 16, 2017

ahmadawais Mar 16, 2017

aduth Mar 16, 2017

ahmadawais Mar 17, 2017

aduth Mar 17, 2017

ahmadawais Mar 17, 2017

aduth commented Mar 16, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

aduth commented Mar 17, 2017

Enhancement: Improve Documentation #278

Enhancement: Improve Documentation #278

Conversation

ahmadawais commented Mar 15, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth Mar 16, 2017 • edited Loading

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth commented Mar 16, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

youknowriad commented Mar 17, 2017

ahmadawais commented Mar 17, 2017

aduth commented Mar 17, 2017

aduth Mar 16, 2017 •

edited

Loading