Generate more descriptive documentation from proto files

Open

#124 opened on Jun 25, 2020 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

internal Progress: ready for grooming

Dominant language: PHP
Stars: 7
Forks: 16
PR merge metrics: No merged PRs in 30d

Description

As I developer, I want to have a good description and documentation of PHP API, so php proto generator should be able to pick comments from proto files and put them in relevant PHP code, README files and configuration.

AC:
* Documentation from proto files is transferred to
* generated methods
* generated services
* Package documentation (readme files)
* description field in composer.json
* Static test must be green

Here is an example of current failures for static test:
```
FILE: ...ode/Magento/CatalogStorefrontApi/Api/Data/VariantArrayMapper.php
----------------------------------------------------------------------
FOUND 2 ERRORS AND 6 WARNINGS AFFECTING 8 LINES
----------------------------------------------------------------------
15 | ERROR | [ ] Final keyword is prohibited in Magento. It
| | decreases extensibility and is not compatible
| | with plugins and proxies.
27 | ERROR | [ ] Comment block is missing
33 | WARNING | [x] Expected 5 space(s) before asterisk; 4 found
34 | WARNING | [x] Expected 5 space(s) before asterisk; 4 found
35 | WARNING | [x] Expected 5 space(s) before asterisk; 4 found
36 | WARNING | [x] Expected 5 space(s) before asterisk; 4 found
37 | WARNING | [x] Expected 5 space(s) before asterisk; 4 found
45 | WARNING | [ ] Line exceeds 120 characters; contains 128
| | characters
----------------------------------------------------------------------
PHPCBF CAN FIX THE 5 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

Magento\Test\Php\LiveCodeTest::testCodeMess
PHP Code Mess has found error(s):
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/CatalogProxyServer.php:61 Avoid unused parameters such as '$ctx'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/CatalogProxyServer.php:577 Avoid unused parameters such as '$ctx'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/CatalogProxyServer.php:1099 Avoid unused parameters such as '$ctx'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/CatalogProxyServer.php:1258 Avoid unused parameters such as '$ctx'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/BundleItemArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/BundleItemOptionMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 10. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/CategoriesGetResponseArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/CategoryArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/CategoryMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 28. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ConfigurableOptionArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ConfigurableOptionMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 10. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/DeleteProductsRequestArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/DeleteProductsResponseArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/DownloadableLinkMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 12. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/GroupedItemArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ImportCategoriesRequestArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ImportProductsRequestArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/MediaGalleryItemArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/OptionArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/OptionMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 24. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/OptionValueMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 21. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductArrayMapper.php:15 The class ProductArrayMapper has a coupling between objects value of 14. Consider to reduce the number of dependencies under 13.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductArrayMapper.php:38 The method convertToArray() has a Cyclomatic Complexity of 15. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductArrayMapper.php:38 The method convertToArray() has an NPath complexity of 16384. The configured NPath complexity threshold is 200.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductArrayMapper.php:38 The method convertToArray() has 138 lines of code. Current threshold is set to 100. Avoid really long methods.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductMapper.php:15 The class ProductMapper has a coupling between objects value of 15. Consider to reduce the number of dependencies under 13.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductMapper.php:76 The method setByKey() has a Cyclomatic Complexity of 70. The configured cyclomatic complexity threshold is 10.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductMapper.php:76 The method setByKey() has 271 lines of code. Current threshold is set to 100. Avoid really long methods.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/ProductsGetResultArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/UrlRewriteArrayMapper.php:20 Avoid unused private fields such as '$data'.
/var/www/html/app/code/Magento/CatalogStorefrontApi/Api/Data/VariantArrayMapper.php:20 Avoid unused private fields such as '$data'.

```
http://10.234.233.97:8080/job/Static-Tests/3904/testReport/junit/Magento.Test.Php/LiveCodeTest/testCodeStyle/

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Research direction

Start by locating the PHP proto generator and review the generated API files under app/code/Magento/CatalogStorefrontApi, along with README files and composer.json. Use the reported Magento\Test\Php\LiveCodeTest::testCodeMess failures as the initial check. Done means proto comments appear in generated methods and services, package README files, and the composer description, with the static test green.

Written by the indexing model from the issue text.

Assessment

Tech stack: php
Domain: api, documentation
Issue type: Feature
Difficulty: 4/5
Estimated time: 3-5 days
Activity status: Stale
Clarity: Mostly clear
Newbie friendliness: 35/100