[BUG][PHP] Too verbose PHPDoc blocks in each file

dkarlovi commented 4 years ago

Bug Report Checklist

[x] Have you provided a full/minimal spec to reproduce the issue?
[x] Have you validated the input using an OpenAPI validator (example)?
[x] Have you tested with the latest master to confirm the issue still exists?
[x] Have you searched for related issues/PRs?
[x] 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
{
}

wing328 commented 4 years ago

Your suggestion to reduce duplicated comments sound good to me.

dkarlovi commented 4 years ago

Need to strip out comments mentioning the generator (or its team) as "authors", see: https://github.com/OpenAPITools/openapi-generator#34---license-information-on-generated-code

wing328 commented 4 years ago

The below is more for growth-hacking to introduce openapi-generator to more users.

 * @author OpenAPI Generator team
 * @see    https://openapi-generator.tech

Auto-generated code in other languages (e.g. Ruby) also put down "OpenAPI Generator team" as the author

dkarlovi commented 4 years ago

@wing328 understandable, but since the code ships without a license by default, as established in https://github.com/OpenAPITools/openapi-generator/issues/7535 and the generated code claims authorship by the generator team, that's at least something to consider.

The generator can be mentioned without it (or its team) being explicitly called the authors of the generated code, those two things seem very different, but IANAL.

Something like "generated with" instead of "author", the author is the user running the tool, no?

OpenAPITools / openapi-generator