How to write comments so Pinocchio formatter will pretty print them

We'll use the Pinocchio for really pretty literary API documentation.

It uses Markdown as the parser for comments, and it highlights the phpDocumentor's tags, too. So, if you still don't know how to mark up the text in Markdown, go and read the page behind this link, really.

Here are the most important caveats and hints:

1. Every file gets the first-level header with the name of file without extension.

2. It's cool to have the second-level header with the name of class before the class declaration.

3. It's even more cool to have the third-level header with the name of method before the public methods declaration. It's not important to have headers on private and protected methods, they are ideologically helpers.

4. One can format the second-level header in comments as follows:

   /*
    *## I'm a second-level header!
    *### I'm a third-level header! Note the absence of space between the asterisk and the sharp sign!
    */
   

5. You can turn any URL string into a link by enclosing it between angle brackets.

6. You can turn any email address into a clickable safe link by enclosing it between angle brackets.

7. Empty line in comment makes the end of one paragraph and start of another. Newlines are insignificant. Note, however, that this applies only to multiline comments. Each single-line comment is treated like a separate paragraph.

8. To make it technically simple: parsing of a comment starts from the comment symbols, like this:

                   /**
   unparsable area  * parsable area starting from space after asterisk
                    *
                    */
   

9. Please note that phpDocumentor's non-inline tags which are traditionally put into the PHP sources do start with a newline in processed document, so even in multiline comments you don't need to separate e. g. lists of @param declarations with empty lines (see p. 7 also).