[BUG][PHP] Too verbose PHPDoc blocks in each file
Created by: dkarlovi
Bug Report Checklist
-
Have you provided a full/minimal spec to reproduce the issue? -
Have you validated the input using an OpenAPI validator (example)? -
Have you tested with the latest master to confirm the issue still exists? -
Have you searched for related issues/PRs? -
What's the actual output vs expected output? -
[Optional] Sponsorship to speed up the bug fix or feature request (example)
Description
Current,y the php
generator produces files with very large headers, close to or exceeding 40 lines. Not only is that way too verbose, it actually lowers the quality of the code since the signal/noise ratio is way off.
This can also be seen in other places where the information is repeated in the PHPDoc block and immediately following it in code, bringing no value.
Solution proposals
- merge information from multiple file PHPDoc blocks into a single shorter one, not repeating itself, take into account code style fixers can change/remove them and design accordingly (for example, one file level one with the the data currently in
partial_header.mustache
, one class level one, example below) - remove PHPDoc comments which just repeat the informaton already obvious from the method APIs: if you have a PHPDoc, it should create value, if it's just repeating the same information, it's not doint that
Example
<?php
/**
* Reddit.com.
*
* Reddit.com API
*
* The version of the OpenAPI document: 1.0.0
*
* Generated by: https://openapi-generator.tech
* OpenAPI Generator version: 5.0.0-SNAPSHOT
*/
namespace Flexolabs\RedditClient;
use Exception;
/**
* @author OpenAPI Generator team
* @see https://openapi-generator.tech
*
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
*/
class ApiException extends Exception
{
}