File descriptions actually do serve a purpose – they are shown under a “Files” menu that’s present in pretty much all templates… admittedly other than the default one.

]]>By: Bruno Skvorchttps://www.sitepoint.com/generate-documentation-with-apigen/#comment-17980
Thu, 02 Aug 2012 14:33:47 +0000http://www.sitepoint.com/?p=3374#comment-17980That’s fantastic, thanks. It’s very refreshing to know the software’s author pays attention to the community this much.
]]>By: Mike van Rielhttps://www.sitepoint.com/generate-documentation-with-apigen/#comment-17979
Thu, 02 Aug 2012 14:24:34 +0000http://www.sitepoint.com/?p=3374#comment-17979I try to read every blog post and tweet related to phpDocumentor. I value community input quite a lot and base decisions on what people want. It also helps me to discover bugs that might not be reported and do not come up in my own tests; which is cool.

Concerning GraphViz; the requirement is annoying. I can’t make it any prettier than it is. We still want to move that to a(n optional) plugin so that people do not hit the dependency.

Concerning the points that you address:

1. One of the improvements that we want to make is to allow errors to be toggleable for one or more file. That way you could switch off the page-level docblock error for your project and/or switch off all errors for your ‘vendors’ directory so that you could parse your dependencies if you’d want to.

4) Since version alpha 7 or alpha 8 we now output the name of the file that is processed and all errors are grouped. Appending the filename after the message cause an unreadable lot of lines in the CLI.
Regarding the error; I will run some tests this evening and contact you by mail. It should not output an error.

5) regarding the HTML tags; I will take a look at that as well. Escaping is probably still enabled for that specific part of the template.

]]>By: Bruno Skvorchttps://www.sitepoint.com/generate-documentation-with-apigen/#comment-17978
Thu, 02 Aug 2012 10:17:01 +0000http://www.sitepoint.com/?p=3374#comment-17978Thanks for the feedback, I had no idea this would actually be read by someone who works on either of those parsers so I’m feeling cautiously optimistic about discussing this!

Just a heads up first: It seems OSX 10.8. introduced new problems in using GraphViz, and since PhpDoc depends on it, I had to do dance around some problems. The situation was finally resolved by doing “brew install libtool”, which graphviz depends on (I guess?) in 10.8. This might be worth including in the PhpDoc documentation, since it might end up being a roadblock to many users.

1) Page level docblocks are optional, yes, but seeing a lot of red on screen and a several lines of warnings like “No page-level DocBlock was found in file Mappers/UserMapper.php” for such a small sample project is quite discouraging – it hints at fatal failure even if none occurred. Perhaps include a –no-pageblock option that defaults to yes?

3) ApiGen indeed does not have a Class Diagram, and this is one of PhpDoc’s major advantages. However, due to the Z index error I found them less than usable. Thanks for fixing this.

4) “The type hint of the argument is incorrect for the type definition of the @param tag with argument $oMapper in __construct()” is the warning I get. I assume this refers to the User class (it would be great if warnings echoed out the files in which they found the errors, too), but as you can see in the source the type hint for it is valid, at least from my perspective, I’m fully aware that I might be missing something. (Fyi the documentation was generated fine – the warning seems unwarranted)

5) I don’t know what I did wrong to make @edit not work, I just tried again and it worked fine. I will edit said part of the article. What I meant to say aside from it was that there’s no html support in the tag description text – html tags will remain visible. I’m not sure if there’s a command to force html parsing of description text, I haven’t found it while looking, so if there is I apologize in advance.

Thank you again for taking the time to read this and provide feedback. If you’d like to get in touch and approach some of the problems in more detail please do so. I’d be glad to give the next PhpDoc release a new try.