[PSR-5] Propose adding section tags to PHPDoc

[Jennifer Hodgdon]

In the Drupal project, we sometimes have very lengthy documentation
blocks.

It is quite useful to break them up into sections. So, we have adopted
the following tags from Doxygen, which I'd like to propose adding to
PHPDoc as well. Example:

...
* @section sec_one Section 1
* One or more paragraphs for section 1 go here.
*
* @subsection sub_a Sub-section A
* One or more paragraphs for sub-section A go here.
* Reference to @ref sec_one can be done like this.
...

Syntax:

@section identifier Rest of line is the name

@subsection identifier Rest of line is the name

@ref identifier
(this last one turns into a within page link with the
section/subsection name, on an API docs site)

Thoughts?
--Jennifer

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

[Marco Pivetta]

Hi!

On 10 July 2014 19:42, Jennifer Hodgdon <yah...@poplarware.com> wrote:

In the Drupal project, we sometimes have very lengthy documentation blocks.

That seems more like a smell, no?
I don't think that writing large docblocks should be encouraged: I know that PSR-5 is about docblock comments, but I still like thinking of "a comment is a lie", especially when larger comments are written.

Marco Pivetta

http://twitter.com/Ocramius     

http://ocramius.github.com/

[Mike van Riel]

Marco, docblocks are not comments, they are documentation. It merely has in common with comments that it exists in the source. Which is a bonus actually :)

--
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/CADyq6s%2BO%3Dd9cejra6LpbVBaPA%3DfFaigQiCUwsv7wAjS6gYHBYQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Marco Pivetta]

Hi Mike,

On 10 July 2014 20:16, Mike van Riel <draco...@gmail.com> wrote:

Marco, docblocks are not comments, they are documentation. It merely has in common with comments that it exists in the source. Which is a bonus actually :)

I'm aware of that, I just believe that:

/**

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic

 * maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic maaaaagic
 */

public function magic()
...

is not a good idea. Doing following is better and also simpler once the documentation is extracted from the docblocks:

Instead

/**

 * Do the thing.
 */

public function doTheThing($withTheOtherThing)
....

[Marco Pivetta]

Clarifying after getting some further feedback by the folks on Stackoverflow:

10~20 lines of documentation in a docblock are _OK_.
10~20 paragraphs of documentation in a docblock are hidden technical debt, and definitely _NOT OK_.

Hope that draws a clear limit around my problem with this suggestion.

Marco Pivetta

http://twitter.com/Ocramius     

http://ocramius.github.com/

[Jennifer Hodgdon]

On 07/10/2014 11:10 AM, Marco Pivetta wrote:
> On 10 July 2014 19:42, Jennifer Hodgdon <yah...@poplarware.com> wrote:
>> In the Drupal project, we sometimes have very lengthy documentation blocks.

> That seems more like a smell, no?
> I don't think that writing large docblocks should be encouraged: I know
> that PSR-5 is about docblock comments, but I still like thinking of "a
> comment is a lie", especially when larger comments are written.

We regularly write long docs on the "pages" mentioned in another
thread I just started. It's a way to provide over-arching summaries of
our API, in a way that is versioned and kept with the code.

[Mike van Riel]

Hi Jennifer,

I know Doxygen captures markup in tags but I have held the stance that
PSR-5 is about documentation and not how generators present their
information; that is something best left to individual generators.

For example, the @filesource tag that phpDocumentor uses is not included
in the spec because that concerns behaviour specific to phpDocumentor.

Of course we already bend the rules a little by presenting Markdown as a
way to format your code in the hopes that people will adopt Markdown but
is it not a required formatting form. An implementor is considered free
in the way they format their descriptions.

(For those wondering, when I refer to Markdown I refer to the one true
spec: http://daringfireball.net/projects/markdown/)

[Jennifer Hodgdon]

OK, sounds like this tag set is just going to be a Drupal extension
then, unless there is a large groundswell of support from other FIG
list members, which I'm not seeing.

Thanks for at least listening!

--Jennifer

[Mike van Riel]

Thanks for bringing it up; it is these suggestions that help make this a
proper spec.

[Alexander Makarov]

@section is a markup thing, not informational thing so I don't think it should be included.

Sometimes we have examples and descriptions in docblocks in Yii.

We're using our own phpdocumentor-compatible generator that supports markdown. It covers sections, lists and all the other nice markup things.

[Sebastian Krebs]

2014-07-12 13:56 GMT+02:00 Alexander Makarov <alexande...@googlemail.com>:

@section is a markup thing, not informational thing so I don't think it should be included.

Sometimes we have examples and descriptions in docblocks in Yii.

We're using our own phpdocumentor-compatible generator that supports markdown. It covers sections, lists and all the other nice markup things.

Isn't it sufficient to just create a custom template and let it parse the markdown-enabled sections? For example in twig

{{ element.description|markdown }}

 

--

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/e8159f82-540f-4ea7-bb28-9420620079b3%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
github.com/KingCrunch