phpdoc-md Multiblock args

This change allows the tool to generate expected Markdown code for method arguments when they have descriptions with complex structures.

For example, given the following docblock:

/**
 * @param string[] $scopes
 *        The OneDrive scopes requested by the application. Supported
 *        values:
 *          - `'offline_access'` ;
 *          - `'files.read'` ;
 *          - `'files.read.all'` ;
 *          - `'files.readwrite'` ;
 *          - `'files.readwrite.all'`.
 * @param string $redirectUri
 *        The URI to which to redirect to upon successful log in.
 */

Without this change, the tool generates:

#### Arguments
* $scopes **array&lt;mixed,string&gt;** - &lt;p&gt;The OneDrive scopes requested by the application. Supported
values:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;&#039;offline_access&#039;&lt;/code&gt; ;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;&#039;files.read&#039;&lt;/code&gt; ;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;&#039;files.read.all&#039;&lt;/code&gt; ;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;&#039;files.readwrite&#039;&lt;/code&gt; ;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;&#039;files.readwrite.all&#039;&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
* $redirectUri **string** - &lt;p&gt;The URI to which to redirect to upon successful log in.&lt;/p&gt;

The problem is that the encoded HTML - which came directly from attributes in the structure.xml generated by phpDocumentor - is rendered as-is in the Markdown file: HTML elements are shown as literal <li>, <code>, ', etc... This problem is exacerbated by the fact that single line breaks are replaced by spaces as per Markdown specification. Ultimately, the description is close to unreadable. This is what you see when viewing the Markdown page on GitHub:

$scopes array<mixed,string> - <p>The OneDrive scopes requested by the application. Supported values:</p> <ul> <li><code>'offline_access'</code> ;</li> <li><code>'files.read'</code> ;</li> <li><code>'files.read.all'</code> ;</li> <li><code>'files.readwrite'</code> ;</li> <li><code>'files.readwrite.all'</code>.</li> </ul>

With this change, the tool generates:

#### Arguments
* $scopes **array&lt;mixed,string&gt;**

    The OneDrive scopes requested by the application. Supported values:

    - `'offline_access'` ;
    - `'files.read'` ;
    - `'files.read.all'` ;
    - `'files.readwrite'` ;
    - `'files.readwrite.all'`.


* $redirectUri **string** - The URI to which to redirect to upon successful log in.

This produces a much more Markdown-friendly description, close to the HTML version that phpDocumentor would generate. It becomes more readable, example here: https://github.com/krizalys/onedrive-php-sdk/wiki/Krizalys-Onedrive-Client

Aug 11 '19 11:08 krizalys

@evert Any update on this?

Aug 19 '19 23:08 krizalys

@evert Any update on this?

Aug 27 '19 14:08 krizalys

phpdoc-md phpdoc-md copied to clipboard

Multiblock args

phpdoc-md
phpdoc-md copied to clipboard