[PSR-5] Propose adding PHPDoc tag for inline code examples

[Jennifer Hodgdon]

I've read carefully through the PSR-5 document, and I think it's
mostly great! Nice work, Mike (and others).... However, it's missing a
few tags that I think would be useful to have in the spec, so I'm
going to suggest each as a separate thread in this mailing list for
discussion.

First: The PSR-5 standard includes tag @example, which is stated to be
for linking to *external* code samples (in other files or URLs).

It is also often useful in documentation to include in-line code
samples embedded in a doc block. Having the code embedded means people
looking at the code can see them without having to find the other
file/URL.

I realize that if your docs parser supports a particular Markdown
syntax, you could probably use that to put in embedded code, but not
all docs parsers support Markdown of any flavor, and I think it is
useful to have a standard PHPDoc syntax to embed code, which would be
independent of a particular flavor of Markdown and therefore supported
by any docs parser.

Proposed example:

/**
* Calculates the foobar.
*
* How to use this function:
* @code {
* $foo = foobar($x);
* }
*
* @param string $bar The input.
*/
function foobar($bar) {}

Obviously, this code example is not very exciting, but in many cases,
function/method/class usage is quite complex, and code samples are useful.

As an alternative to introducing a @code tag, this could just be a 3rd
alternate syntax for @example (replace the @code tag in my sample with
@example). I think either way would be fine.

And as a note: in the Drupal project, we actually use a
@code...@endcode syntax, for historical reason. I've used @code{...}
here because I think it is more consistent with the inline PHPDoc
syntax used elsewhere in the PSR-5 proposal.

Thoughts?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal web sites and custom Drupal modules

[Sebastian Krebs]

My 2 cents: This and most (all?) the other suggestions you made are in my opinion better covered by Markdown (or similar). For example this one is covered by every formatting syntax I know

```php

$foo = 'bar';

```

    $foo = 'bar';

and so on.

To me it looks like the suggestions you made just end up in a new formatting syntax.

Sooo: Why don't you just use Markdown? :)

 

   --Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal web sites and custom Drupal modules

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/53BECAA2.9030605%40poplarware.com.
For more options, visit https://groups.google.com/d/optout.

--
github.com/KingCrunch

[Jennifer Hodgdon]

On 07/10/2014 12:53 PM, Sebastian Krebs wrote:

> My 2 cents: This and most (all?) the other suggestions you made are in my
> opinion better covered by Markdown (or similar).

...

> Sooo: Why don't you just use Markdown? :)

That is a good question. :)

We aren't using Markdown because:

a) There is no one definition of "Markdown", but many flavors. If we
have tags defined, then any docs parser that supports PHPDoc will have
to interpret it in the same way. You may think that all Markdown
flavors use ````php to denote PHP code, but I do not believe this is
the case (for instance, AsciiDoc, which actually has definite
standards and can be considered a "markdown syntax" -- note the
non-capitalization of markdown here -- does this in a different way).

b) History: The Drupal coding standards and docs parser are old, and
based on the even older Doxygen, which had these tags (most likely
preceding Markdown becoming popular, but I don't know for sure).

c) There are advantages of having explicit tags rather than using
Markdown for everything, because they provide symantics and not only
"how to display something".

For example, @param denotes "Function parameter", @throws denotes
"This function throws an exception", etc. So if we do not need @code
or maybe @example expanded to handle inline code, why should we have
@example or @see either (for the URL formats), when you could just
make a link using Markdown too? The reason is that @see means one
thing, and @example means something else, and they're both specific
semantics of a relationship between the item being documented and some
other information.

So... I think the relationship of "provides an example" is a useful
one to denote with a tag, not just "format this as code".

Note: We can still continue to use our tags; if no one else thinks my
proposed tags are useful and they don't make it into PSR-5, we can
still use them as "extensions", so this is not a show stopper. Just
suggestions. :)

[Mike van Riel]

Hi Jennifer and Sebastian,

I am doubting about this; I can definitely see where this comes from. I
think it might be interesting to have @example support multiline code
examples instead of just including another file; and perhaps an inline
tag counterpart for use in the description (inline tags generally have
the format `{@example ... }}`; in this case the line closed with a
double closing brace as this is consistent with other inline tags).

I personally think that using Markdown is a good alternative but again,
Markdown is not required in PHPDoc and I can see the need and how it
serves a reader (not only a doc generator). And for your information,
when I talk about Markdown I generally talk about the one true markdown:
http://daringfireball.net/projects/markdown/. All other Markdowns are
derived from it.

> And yes, I prefer Restructured Text above Markdown but for some
reason Markdown really caught on and ReST didn't.

Kind regards,

Mike

[Hari K T]

This is an interesting topic. I have seen the doc comments being passed and create docs in lithium.

Eg code https://github.com/UnionOfRAD/lithium/blob/master/net/http/Router.php#L186-L197 .

A detailed description is over here how they embed the code etc and how they are using.

https://github.com/UnionOfRAD/li3_docs#markdown-syntax

Hari K T

You can ring me : +91 9388 75 8821

http://harikt.com , https://github.com/auraphp , http://www.linkedin.com/in/harikt , http://www.xing.com/profile/Hari_KT

Skype  : kthari85

Twitter : harikt

--

You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/53BF03F3.8040402%40gmail.com.

[Larry Garfield]

I would fully support having an @-based way of providing inline code examples, for pretty much all the reasons that Jennifer listed.  Even if we say that we're only using "the one true Markdown" (which, sorry, I find amusing since I've never used a system that used that one true Markdown without futzing with it, ever), having a "native" way to delineate code is valuable.

As Mike said, PSR-5 isn't aiming to address formatting.  However, this isn't about formatting.  It's about semantics.  Semantically identifying a block of text as a usage example is a valid use case and one that I believe we should support directly.

(Although, I grant, that then begs the question if we should allow for non-PHP code samples and how to identify those.  Eg, I could see a use case for a YAML snippet that would be relevant to a PHP class in some frameworks.)

--Larry Garfield

[Jennifer Hodgdon]

On 07/10/2014 06:34 PM, Hari K T wrote:
> This is an interesting topic. I have seen the doc comments being passed and
> create docs in lithium.

.... [example] ....
>
> https://github.com/UnionOfRAD/li3_docs#markdown-syntax

This clearly illustrates my point -- they use

{{{ code here }}}

for embedded code samples. The "one true" Markdown uses:

````
(code here)
````

Asciidoc uses

[source,php]
----
(code here)
----

for extended samples, and +a_function()+ for smaller snippets. So
there is clearly not just one way to do this...

How about a tag? :)

[Mike van Riel]

On 11-07-14 21:35, Jennifer Hodgdon wrote:
> On 07/10/2014 06:34 PM, Hari K T wrote:
>> This is an interesting topic. I have seen the doc comments being
>> passed and
>> create docs in lithium.
> .... [example] ....
>>
>> https://github.com/UnionOfRAD/li3_docs#markdown-syntax
>
> This clearly illustrates my point -- they use
>
> {{{ code here }}}
>
> for embedded code samples. The "one true" Markdown uses:
>
> ````
> (code here)
> ````
>
> Asciidoc uses
>
> [source,php]
> ----
> (code here)
> ----
>
> for extended samples, and +a_function()+ for smaller snippets. So
> there is clearly not just one way to do this...
>
> How about a tag? :)

Hi Jennifer,

I hope I was not too unclear on the subject; I see the need for an
inline example tag and to expand the current example tag to be able to
show inline code examples. No debate there from me :)

When talking about Markdown; you can usually rely that all dialects only
expand on the original, which I mockingly called the 'one true' (though
I get the feeling that I am being mocked now) at
http://daringfireball.net/projects/markdown/syntax.

A code block in the original spec is an indentation of four lines,

Such as this

The syntax that you mention (using three backticks around a block of
text) is called Extended Markdown and is also featured by GHFM (Github
Flavoured Markdown).

I am very aware of the large amount of dialects in existence (that is
why I love ReST much more) but the basic Markdown provided by Daring is
a proper ancestor and _should_ encapsulate all dialects.

Capturing formatting in another DSL using tags seems redundant to me as
there are better and more mature alternatives (HTML, Markdown, Textile,
ReST, etc).

Just to be sure I am not misunderstood due to that awfully pedantic rant
above I would want to repeat: I agree with you and Larry that @example
and its inline variant offer a semantic value on top of potentially
formatting it. It is due to this semantic value that I think it makes a
good change

[Nate Abele]

I was asked to chime in here, so here's my two cents, for whatever that's worth. :-)

First of all, totally agree with Larry's sentiments re: the 'one true Markdown'. I dunno if it's out of scope for this effort, but that might be worth standardizing on, at least to provide a baseline (and allow for extensions that could eventually be incorporated into the main spec).

On Friday, July 11, 2014 3:35:21 PM UTC-4, Jennifer Hodgdon wrote:

On 07/10/2014 06:34 PM, Hari K T wrote:
> This is an interesting topic. I have seen the doc comments being passed and
> create docs in lithium.
.... [example] ....
>
> https://github.com/UnionOfRAD/li3_docs#markdown-syntax

This clearly illustrates my point -- they use

{{{ code here }}}

for embedded code samples. The "one true" Markdown uses:

````
(code here)
````

I'm not too particular on the syntax for wrapper characters, but I believe what Hari meant to point to was how we handle code embedding, for example: https://github.com/UnionOfRAD/lithium/blob/master/net/http/Media.php#L17-L32

Which renders out as: http://li3.me/docs/lithium/net/http/Media

It was actually an idea we stole from Perl, which provides a way of keeping documentation in sync with unit tests. Doing it that way (i.e. embedding unit tests, as opposed to writing code inline in the doc) has some convenient side-effects:

- Cases requiring more complex setup can be validated in an automated way, while only embedding the relevant portions in the documentation

- Snapshotting and hashing extracted code allows documentation to be flagged for review when code behavior (hence, unit tests) changes

- Some other stuff, but my memory is failing me right now

I don't love the syntax we used, but it worked for us. The important part, as far as I'm concerned, is being able to embed actual runnable code examples that can be validated in an automated way.

[Hari K T]

I'm not too particular on the syntax for wrapper characters, but I believe what Hari meant to point to was how we handle code embedding, for example: https://github.com/UnionOfRAD/lithium/blob/master/net/http/Media.php#L17-L32

Which renders out as: http://li3.me/docs/lithium/net/http/Media

You are right. I was trying to point the same.

Thank you Nate for taking time to explain.

[Alexander Makarov]

We at Yii are using github-compatible markdown for the purpose.

[Philipp Gampe]

Hi.

I don't love the syntax we used, but it worked for us. The important part, as far as I'm concerned, is being able to embed actual runnable code examples that can be validated in an automated way.

I do not think this is really a use case for most projects. Usually the unit tests require mocking at least some part of the framework away.

What is miss hover is a way to specify the expected return value of the method, not as an internal return type (@return), but how it will produce output on a website.

E.g. consider https://git.typo3.org/?p=Packages/TYPO3.CMS.git;a=blob;f=typo3/sysext/fluid/Classes/ViewHelpers/Form/CheckboxViewHelper.php which is part of a template engine that produces html output.

The description is supposed to provide information even to non-developers: http://api.typo3.org/typo3cms/master/html/class_t_y_p_o3_1_1_c_m_s_1_1_fluid_1_1_view_helpers_1_1_form_1_1_checkbox_view_helper.html

You can see that each sample is split into what you have to write into your template (could be some kind of configuration file as well), and what you will get later on.

If you want to go down the markdown road, please much sure to define samples that confirm to the common ReST and Markdown markup: https://gist.github.com/dupuy/1855764

Personally, I would love to define a subset of markdown as a standard way to provide rich text description for both classes and methods.

[sun]

Clarification #1:  Drupal even uses @code [...] @endcode as an Inline PHPDoc construct (within e.g. @param), in order to explain common usage or parameter values.  Random example:

/**
 * @param $settings_items
 *   An array of settings arrays, as returned by:
 *   @code
 *     $js = _drupal_add_js();
 *     $settings_items = $js['settings']['data'];
 *   @endcode
 */

That kind of structural misuse of PHPDoc tags within PHPDoc tags made me cringe for many years.


Clarification #2: There may be multiple code blocks within a single PHPDoc description.  It is the PHPDoc description that constructs an actual "document" that is worth to read, including code examples.

As such, usage of @code tags is vastly different to @example — they do not necessarily represent self-contained example code, they represent code that is relevant to the current context of the PHPDoc description.  A big difference, conceptually, semantically, and linguistically.

Documenting code up to this level might sound extra-terrestrial to some of the audience here, but it's a proven path to adoption and success, kthxbye. ;-)


Clarification #3: Most code using these kind of @code tags is legacy ~PHP4 code.  The use-case is almost non-existent in modern, decoupled PHP5 code.  However, PSR-5 does not make such a differentiation.


I fully agree that Markdown offers much more powerful ways to achieve the same.  IMO, we should formally adopt backticks (`) for inline code, and fenced code blocks (```) for multi-line code blocks in PHPDoc.  The latter optionally allowing for language specifiers (```yaml), which MAY be optionally supported by your PHPDoc generator of choice; otherwise simply rendered as PRE-formatted text.

/**
 * @param $settings_items
 *   An array of settings arrays, as returned by:
 *   ```
 *   $js = _drupal_add_js();
 *   $settings_items = $js['settings']['data'];
 *   ```
 */

The PSR-5 spec does actively mention, encourage, and support Markdown in various ways already (primarily in descriptions for strong, emphasized, and list formatting), so advancing to inline + GFM-style fenced/multi-line code snippets sounds more than natural to me.

For completeness, the backtick operator is PHP core's internal alias for shell_exec(), so any usage of this character involves a security risk that is worth to mention. — However, you'd have to trip up your PHPDoc in serious + very unfortunate ways to produce something that doesn't produce a PHP Fatal Error to begin with, and even in the worst of all cases, the contained PHP code is hardly understood by any shell.  Due to that, it should be safe to adopt the backtick character.

[Mike van Riel]

On 16-08-14 04:53, sun wrote:

Clarification #1:  Drupal even uses @code [...] @endcode as an Inline PHPDoc construct (within e.g. @param), in order to explain common usage or parameter values.  Random example:

/**
 * @param $settings_items
 *   An array of settings arrays, as returned by:
 *   @code
 *     $js = _drupal_add_js();
 *     $settings_items = $js['settings']['data'];
 *   @endcode
 */

Interesting example: this text will be interpreted as a DocBlock having three tags: @param, @code and @endcode and the intended interpretation is not supported by the PHPDoc DSL (not currently and not in PSR-5).

This is because the definition of a tag is that when an *@ followed by a 'word' or 'annotation' is encountered as the first non-whitespace character on a line* that any text following it, until the next *@ followed by a 'word' or 'annotation' is encountered as the first non-whitespace character on a line*, is considered part of the tag.

The @code and @endcode are, according to that definition, tags separate from the @param. This is also why the concept of inline tags exist (`{@tag ... }`), so that tags may be used inside a description without breaking the flow.

Clarification #3: Most code using these kind of @code tags is legacy ~PHP4 code.  The use-case is almost non-existent in modern, decoupled PHP5 code.  However, PSR-5 does not make such a differentiation.

Correct, PSR-5 does not cover PHP4 by design. That is also why we could drop tags such as @public, @protected, @private, @static an so forth.

I fully agree that Markdown offers much more powerful ways to achieve the same.  IMO, we should formally adopt backticks (`) for inline code, and fenced code blocks (```) for multi-line code blocks in PHPDoc.  The latter optionally allowing for language specifiers (```yaml), which MAY be optionally supported by your PHPDoc generator of choice; otherwise simply rendered as PRE-formatted text.

/**
 * @param $settings_items
 *   An array of settings arrays, as returned by:
 *   ```
 *   $js = _drupal_add_js();
 *   $settings_items = $js['settings']['data'];
 *   ```
 */

The PSR-5 spec does actively mention, encourage, and support Markdown in various ways already (primarily in descriptions for strong, emphasized, and list formatting), so advancing to inline + GFM-style fenced/multi-line code snippets sounds more than natural to me.

I agree with Jennifer here that it should be unambiguous which Markdown is meant. The original [Markdown specification](http://daringfireball.net/projects/markdown/syntax) does not contain the fenced notation. So either we standardize on a more specific Markdown specification, such as [Github Flavored Markdown](https://help.github.com/articles/github-flavored-markdown) or accept that fenced blocks are not part of this proposal.

A downside to using unofficial dialects of Markdown, such as GFM, is that they are generally living documents whereas the original version of Daring Fireball is stable.

For completeness, the backtick operator is PHP core's internal alias for shell_exec(), so any usage of this character involves a security risk that is worth to mention. — However, you'd have to trip up your PHPDoc in serious + very unfortunate ways to produce something that doesn't produce a PHP Fatal Error to begin with, and even in the worst of all cases, the contained PHP code is hardly understood by any shell.  Due to that, it should be safe to adopt the backtick character.

This is a non-issue. The contents of DocComments should never be evalled and are to my knowledge never executed.

[Mike van Riel]

Hi Nate,

Currently PHPDoc and PSR-5 does not describe a way to include the contents of a method by its FQSEN. Is this something you would like to propose as an addition?

Mike

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/296d23bc-835b-4346-97c8-1dd62dbfacb1%40googlegroups.com.

[Bernhard Schussek]

I pretty much agree with what sun said. Given how many developers use GitHub and are familiar with GitHub-flavored Markdown, it seems straight-forward and pragmatic to me to use that dialect for doc blocks as well.

As safe-guard against future changes to that dialect, we can add a copy of the status quo of GFMD as appendix to the PSR.

--

Bernhard Schussek
Blog: http://webmozarts.com
Twitter: http://twitter.com/webmozart

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/969f2b8c-270a-4072-a246-3186134fb59d%40googlegroups.com.