Skip to content

Multi-line descriptions break the docblock format #120

Description

@siggi-k

Affects 2.0-beta5 (5b657bf).

A model with x-table: false renders every property description raw into the docblock, so a
multi-line description (YAML description: |) loses the * prefix from its second line on
and gains a stray empty line from the block scalar's trailing newline:

    /**
    * @var string Oldest day the requested series together can hold data for.
It is the earlier of the company creation date and the oldest counted booking.
Unlike dateFrom it does not follow the request, it describes the data itself.

    */
    public $windowStart;

Cause

src/generator/default/model.php concatenates the description without touching its newlines:

    * @var <?=$attribute->phpType.' '.$attribute->description.PHP_EOL?>

The class-level description in the same template already does it right:

 * <?= empty($model->description) ? '' : str_replace("\n", "\n * ", ' ' . trim($model->description)) ?>

So the attribute line needs the same trim() (kills the empty line) plus a str_replace() with
the 4-space prefix ("\n * ").

Scope

  • Only model.php, i.e. x-table: false. dbmodel.php renders @var with the type alone, so
    DB-backed models are unaffected.
  • Same file, minor: the class-level line prepends ' ' before the description ( * Aggregated …,
    two spaces) and always emits an empty * line before */.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions