Feature request from alankent, posted on GitHub Jan 30, 2015
The complete suite of Magento developer documentation will consist of content from multiple sources. There are guides that the documentation writing team are developing (such as at http://devdocs.magento.com), more traditional online documentation generated from PHP Doc comments, and potentially other automatically generated documentation on REST/SOAP APIs and similar.
This issue is an invitation for the community to help with the PHP Doc aspect of documentation generation. There are several aspects to this work:
- Try some different tools to see which are best able to support Magento. This relates to usability of output, speed and robustness of the tool, etc.
- One proposal is to not generate documentation for all classes, but instead restrict the published documentation to only those classes and methods that the Magento team recommends being used. Such classes and methods could be annotated by “@api”. As such, it is desirable for the tool to be able to use @api as a flag of what to include in the generated output. This may involve modifying an existing tool as there may be no PHP Doc generation tools today that support this functionality.
- Support for official Magento branding is also important. The core team can apply this branding (most likely following the same style and themes as the current documentation site). The objective is to take into account this requirement when selecting which tool to use.
- Incorporation of documentation generation into the current documentation publishing on GitHub is desirable, but not mandatory.
- An interesting future question is whether content developed by tech writers and PHP generated documentation can be merged. For example, having sample code linked to from the PHP Doc, or having links from guides to PHP Doc (without hard coding URLs to a specific web site). It is desirable to generate a single set of documentation that included both PHP Doc and guides.
In general, the goal is to get something up relatively quickly and deliver a useful short term result, restricted to PHP Doc. To set expectations, it may be this tool is temporary until replaced by a more encompassing solution for all documentation.
The goal is to lower the barrier to people exploring the Magento 2 code base today. Once the PHP Doc documentation is published, a desirable side effect is to then encourage greater contribution to improve the quality of the PHP Doc comments within the code base.