[meta] Module Checklist for Examples

This document is a reference for evaluating the completeness of examples modules. It is marked as belonging to the 8.x-1.x branch, but it applies to all examples.

It's meant to evolve, so please comment and update if necessary.

Examples Module Checklist

QA

• Functional tests of all paths defined by the module.
• Functional tests which submit forms and verify that they behave as expected.
• Functional tests of permission-based restrictions.
• Unit tests of code which is not presentational (think 'model' in 'model-view-controller').
• Pass coding standards tests. (See: STANDARDS.md)

Documentation

• Provide docblocks and inline comments for as much code as possible/reasonable.
• Make docblocks usable by api.drupal.org.
• Clearly explain why code exists and what patterns are being used.
• Define a group for the example module, using @defgroup. The name of the group should be the module name.
• The main @defgroup docblock should:
  • Provide an overview of what the module does and how it works.
  • Allow a total Drupal newbie to understand whether they're even looking at the right documentation.
  • Give enough overview that an advanced user could read it and have a basic understanding of the API in question.
  • Provide links to general topics and d.o documentation, using @see and @link.

Usability

• The Examples project only supports core Drupal APIs with examples, so no contrib modules should ever be dependencies of Examples modules. The user should not have to install anything else.
• A top-level README file will explain how to use the examples, and provide pointers to sub-module READMEs if they exist.
• Sub-module READMEs should only describe unusual installation or configuration instructions. We anticipate not needing these.
• In-code documentation is the main source of knowledge.
• Users should be able to browse all in-code documentation on api.drupal.org.
• Provide an in-site documentation page at path examples/[module name], which appears in the default menu. At minimum, this page exists so that users who have enabled the module will have something to see and read, rather than assume the module does nothing or that they made a mistake.
• As much as possible, use twig templates for large text blocks in controllers. #2660058: [meta] Convert controller content to twig {% trans/endtrans %} templates per module
• Other paths provided by the module should follow the pattern examples/[module name]/[feature].