Class methods: use docblock description for example code

[distantnative]

Uses the core code docblocks to display the whole description of the method docblock as Example.

@bastianallgeier @lukasbestle
What do you think about this idea? I think it would allow us to add more examples in-code that we would never maintain manually in the reference. But are there docblocks featuring other description parts than examples?

[lukasbestle]

I like the idea to allow both: For simple methods we could add the example directly to the code (making it accessible to IDEs as well), for complex methods we could add a basic example to the code but still override the field in the reference with more detailed examples.

The description for phpDocumentor is everything after an empty line in the description, right? Don't think we use that for much other than examples so far. However I think the syntax is all over the place. If I remember correctly, we mostly use <code>. Those would need to be converted to Markdown syntax for proper highlighting.

Maybe we need to run over all classes with a script and if the description is not empty, print those methods out to review and fix them manually.

[bastianallgeier]

I really like the idea as well. Do you have a good example link where the doc block is used? I was trying to find something but I can only find those with the Example field.

[distantnative]

@bastianallgeier I don't think our core code is using that much (at all?) yet. That we would have to start to do.

[bastianallgeier]

I thought we already had more examples in the code. I think it's a good idea to follow @lukasbestle's idea and create such a review list to see what we are getting out of it.

[lukasbestle]

A search for * <code> in our core source returns 40 results. Then we also have 15 with * ```. Maybe there are more with different syntax all-together. As I wrote, we can find those by looping over all classes with the PHPDocumentor class and listing all methods that have a description in the docblock.