Background:
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- review / write the hook_help text according to help guidelines

Files: 
CommentFileSizeAuthor
#13 2091415-rest-help-text.patch1.25 KBCrell
PASSED: [[SimpleTest]]: [MySQL] 59,858 pass(es).
[ View ]
#9 rest-help-text-2091415-8.patch1.26 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,869 pass(es).
[ View ]
#6 interdiff.txt1.25 KBbatigolix
#6 rest-help-text-2091415-6.patch1.26 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 59,881 pass(es).
[ View ]
#4 interdiff.txt1.15 KBbatigolix
#4 rest-help-text-2091415-4.patch1.22 KBbatigolix
PASSED: [[SimpleTest]]: [MySQL] 60,140 pass(es).
[ View ]
#1 rest-help-text-2091415-1.patch1.16 KBpokurek
PASSED: [[SimpleTest]]: [MySQL] 58,889 pass(es).
[ View ]

Comments

Status:Active» Needs review
StatusFileSize
new1.16 KB
PASSED: [[SimpleTest]]: [MySQL] 58,889 pass(es).
[ View ]

Insert an url to handbook as is, with no sanitization or formatting.

Status:Needs review» Needs work

The link format is correct, but the some more changes to the wording are needed.
(1) The link to the documentation page should be: "For more information, see the online documentation for the Foo module." according to the help text standard.
(2) " a framework for exposing Drupal's data structures": I think we are trying to avoid the use of "Drupal" in the help texts, so that the texts still appear relevant in other distributions as well. Maybe there is a way of phrasing this more generic?

Regarding (2), if that is the case then we would need to update a lot of other help texts! Many of them are saying Drupal. I wouldn't worry about that right at the moment.

Issue summary:View changes
Status:Needs work» Needs review
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules
StatusFileSize
new1.22 KB
PASSED: [[SimpleTest]]: [MySQL] 60,140 pass(es).
[ View ]
new1.15 KB

patch:

- addresses points raised in #2
- change reference to module (use exact moudle name)
- changes wording in 1st 2 phrases

Title:Create hook_help for Restful Web Services moduleUpdate hook_help for Restful Web Services module
Status:Needs review» Needs work

This mostly looks great!

However, it seemed a bit scary to me when I read this part: "This allows other applications to remotely read and update entity types like site content"... I don't think that just turning on this module would allow other applications to update your content! So maybe the phrasing here should be something more like "The framework can be used by other modules to allow other applications to remotely ..."?

Also, before "and" we need a comma in the long list of entity types.

StatusFileSize
new1.26 KB
PASSED: [[SimpleTest]]: [MySQL] 59,881 pass(es).
[ View ]
new1.25 KB

New patch that addresses point made in #5

Status:Needs work» Needs review

Component:documentation» rest.module
Status:Needs review» Needs work

Looks great! The http://drupal.org link should be https: (sorry I missed that one before). And I think we should move this over to the REST module so the maintainers can comment.

Status:Needs work» Needs review
StatusFileSize
new1.26 KB
PASSED: [[SimpleTest]]: [MySQL] 59,869 pass(es).
[ View ]

http --> https

Looks good to me. I think we can safely skip the usual manual test in this case too.

Any comments from the REST module maintainers (klausi or Crell)?

If it looks good to you, please mark RTBC and move it back to the "documentation" component, and I or someone else can get it committed after the 23rd when we're off the "majors and criticals only week".

I see 2 problems with #9:

1) Technically this module *does* expose entities on its own; no new module is needed for that. However, it is all opt-in. You need to edit a config file (or use a contrib UI module for now) to actually expose something.

2) The reference to "entity types" worries me. The way it reads, it sounds like you can update the entity type: Vis, change the configuration of the entity type. You can't do that; we deliberately aren't providing support for config files via REST (although one could write such support). What you're updating is the entities, and specifically "content entities". And that's just with REST itself. You can expose *any* resource type through REST module, and we actually offer watchdog logs, too, as an example.

We arguably don't need to go to that level of detail here, but it's at least a little misleading to say "entity types".

Status:Needs review» Needs work

OK... Can you propose different text then? The text in #9 was just an attempt to make what was already in the hook_help() a bit more readable (really, it has exactly the same information in it, with slightly different wording, and an expanded list of entity types).

Status:Needs work» Needs review
StatusFileSize
new1.25 KB
PASSED: [[SimpleTest]]: [MySQL] 59,858 pass(es).
[ View ]

Something like this? (Incidentally, WHY are we not wordwrapping obscenely long strings when we get testy about comment lines that are 80.5 characters?)

Status:Needs review» Needs work

I have no idea on wrapping the strings except that we definitely do want them to stay as all one string for translators. Out of scope for this issue anyway.

So... Here's the new proposed text from this patch:

The RESTful Web Services module provides a framwork for exposing REST resources on your site, both read and write. Out of the box it provides support for entities such as content, users, taxonomy terms, etc. that can be enabled. Other modules may add support for other types of REST resource. For more information, see the online documentation for the RESTful Web Services module.

There are several problems, I think:

a) The wording is awkward and I don't think we should use the phrase "out of the box" at all.

b) This now says that the REST module provides support itself for several types of entities and says they can be enabled, but doesn't say how to enable them. Do we need a Uses section?

c) "framwork" is misspelled.

d) We lost the text from the previous patch that said something to the effect that this module doesn't really do anything itself and you'll need to use a different module to actually provide the REST operations. Isn't that true? The text proposed left me thinking that just enabling the REST module would mean you could do REST operations on a site. Now I'm really confused.

Re #14:

b) It provides support for *content* entities. See also below re uses.

d) Yes, that is exactly what you can do, after manually changing a yml config file, or by using the contrib rest_ui module. The documentation has infos about that, see for example https://drupal.org/node/2096019. You don't need any other modules to integrate with content entities.

In that case, we definitely need a "Uses" section that describes how to use this module. It should describe how to enable content type support (linking to the contrib module is great as well as saying there is a YML file), and then describing how to make a REST request.

http://lin-clark.com/blog/2014/01/22/setting-up-rest-drupal-8/ should cover what we need here pretty well :)

Edit: And according to that, the node resource is enabled by default, so you don't even have to do that (you still need to grant permissions).

Great! Then someone just needs to write it up in a couple of concise Uses items. :)