On #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files, we made a patch that included a stub Topic page for api.drupal.org (i.e., a @defgroup) titled:
REST and third-party application integration.
This can be found in file core/modules/system/core.api.php where it says
@defgroup third_party
The documentation to go on this page needs to be written. The idea is:
a) Write a few paragraphs about the topic.
b) Link to more detailed documentation on
https://drupal.org/developing/api/8
c) If the more detailed documentation does not yet exist, create stub page(s), link to the stub pages, and add a note to this issue stating that the stub pages need to be filled out.
d) If the topic has related classes, interfaces, and functions, add
@ingroup third_party
to their documentation headers. That will make these classes etc. show up on the Topic page on api.drupal.org.
For more info -- documentation standards for @defgroup/@ingroup:
https://drupal.org/coding-standards/docs#defgroup
| Comment | File | Size | Author |
|---|---|---|---|
| #5 | 2216523-rest-docs-5.patch | 9.48 KB | jhodgdon |
Comments
Comment #1
jhodgdonI am at least temporarily moving this into the REST module issue queue.
As the maintainers of the REST and Basic Auth modules no doubt know by now (from how the issues for hook_help() went for those modules), I am kind of clueless about this stuff. So it would really be better if one of the maintainers could take a first pass at writing an overview for developers of this topic.
Since this is going into an api.php file as a @defgroup, the idea is to give a basic overview and link to more information (on drupal.org, or other topics) rather than providing a comprehensive tutorial. Also, relevant classes and functions should be added to the topic with @ingroup (see issue summary above).
If you click through to the parent issue, and look at the "child issues" sidebar, you can find other issues that have been completed to give you an idea of what is needed. Or start at the api.drupal.org landing page for Drupal 8, and click into topics (nearly all of them are done now, except this one and a few others that are still open on the parent issue).
Comment #2
jhodgdonAnd if you prefer, you could give an outline of what needs to be written here, or a link to the relevant existing more comprehensive documentation, and I can give it a shot. Thanks!
Comment #3
klausiI'm a bit busy these days, so not sure if I will have time to write this.
General docs for REST are here: https://www.drupal.org/documentation/modules/rest
Comment #4
jhodgdonThanks -- that's a great starting point. I forgot that you had created that section... I can probably write something shorter up based on that section, and then maybe you can review it?
Comment #5
jhodgdonHere's a first patch at a patch.
Comment #6
klausiWow, quite a lot! I personally think that the "@section sec_rest Enabling REST for entities and the log" is a bit too much detail, a reference to the doc page might be enough. It is also a bit confusing without the actual config example in the doc page, which does a better job at explaining with examples. Anyway, there is a reference to the doc page, so this ok.
Overall well written and the content looks correct. So I would say this is RTBC, whether we keep or remove the one section I mentioned should not hold this back.
Comment #7
alexpottCommitted b16acb2 and pushed to 8.x. Thanks!