Nelmioapidocbundle: Enable multi line strings in ApiDoc annotation.

[mjeri]

In my current project I am facing the problem that we have very long descriptions in our annotations. Can we somehow enable a mechanism to add line breaks in the annotations?

Of course I would create a PR for this on my own, but I first wanted to discuss if this is desired and how a implementation could look like.

[ogizanagi]

Line break is already available for docblock comments describing the API services.

Simple way to achieve this is to use the <br/> tag:

     /**
     * This service allow you to retrieve a user by its identifier.
     * <br />identifier could be the email or username.
     *
     * @RESTApiDoc\ApiDoc(
     * [...]
     *  description="Retrieve an user.",
     * )
     **
     * @param int $identity User identity
     * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
     * @return \FOS\RestBundle\View\View
     */
    public function getAction($identity)
    { 
         ... 
    }

[mjeri]

Hmm, I have meant the strings in the description="" party. I have some descriptions in there that are several hundred characters and I want to break them directly in the comment. This leads to rendering of a \n * in the html output as it is just added to the comment.

Maybe a sanitazion of those characters in the proper Extractor would be possible?

[ogizanagi]

I think the intent of the description annotation is to be very short. Several hundred characters seems way too large for a short service description.
That's why I preconized you to use the docblock comment, which add "Documentation" section in the Nelmio Doc, HTML & Markdown compatible.

[willdurand]

Yes, the description field must be short.

[mjeri]

Kk, thanks for the response.

[bgaillard]

Hi, we recently started to document an API with Nelmio, its great, thanks !

But, we encounter several cases where short documentation is not possible...

I think having short descriptions is a good advice but their are many cases where it is simply not possible. For example in our project its not rare to have the need to explain several business rules associated to a parameter or a filter, etc...

In my opinion saying the description field must be short is in most cases a very good advice but when this advice forces developers to write not complete documentations it becomes a bad advice. :confused:

It would be great to be able to write a documentation like this :

/**
 * A method documented.
 * @ApiDoc(
 *         filters = {
 *             {
 *                 "name" = "my_filter",
 *                 "description" = "multiline documentation multiline documentation multiline  
 *                                  documentation multiline documentation multiline documentation
 *                                  multiline documentation multiline documentation multiline 
 *                                  documentation."
 *             }
 *         }
 *     },
 * )

So would you agree to reopen this case ?

I'm willing to create a PR but don't know exactly where it would be good to apply this multiline documentation processing.

Perhaps inside the toArray() method of the ApiDoc class ? Here is a first attempt...

// Ugly code (has to be refactored), this is just a sample to allow multi-line description on filters
public function toArray()
{
...
    if ($filters = $this->filters) {

        foreach($filters as $filterName => $filter) {
            $filter['description'] = preg_replace('/\n\s+\*\s+/', ' ', $filter['description']);
            $filter['description'] = preg_replace('/\s+/', ' ', $filter['description']);
            $filter['description'] = trim($filter['description']);
            $filters[$filterName]['description'] = $filter['description'];
        }
    }
...

[mfsianoopj]

Hi,

Nelmio is very helpful in documenting. But as pointed out by others above in this thread, the description part sometimes happens to be a bit large and when it extends to multiple lines, the character '*' gets rendered in the HTML output. It would be great if its handled.

Thanks

[devantoine]

Similar to this, if markdown is working in the PHPDoc how to get line breaks without HTML?
Currently my PHPDoc is a mix of markdown and html :/

Reading these slides, at the end the generated documentation gots line break but I'm not able to reproduce this.

Any clue?