Last modified: 2013-04-25 15:47:36 UTC
Currently @var declarations are used in comments to specify the type of a variable. Unfortunately, Doxygen doesn't support this use of @var. What's even worse: it simply ignores comment blocks in which @var is used and doesn't include them in the output. See also https://bugzilla.gnome.org/show_bug.cgi?id=626105
What are you proposing we do here? @var declarations are very useful for auto-suggesting in IDEs, and I'd hate to remove them just because Doxygen is broken.
We could ignore this, and maybe move any additional comments from inside a comment block with @var to a separate block. We could also duplicate all @vars decls with another type decl in a separate comment block just for the sake of doxygen. Another option might be to use an input filter for doxygen which rewrites @var decls to something doxygen can handle (like http://stackoverflow.com/a/8472180/276152). Or maybe there is an acceptable, more PHP-friendly doc-generation tool?
Have you looked to see if there is a bug and/or patch for doxygen?
This is the 'official' bugreport Doxygen: https://bugzilla.gnome.org/show_bug.cgi?id=626105 (Doxygen uses bugzilla.gnome.org). I haven't found a patch. But there is actually an easier solution, which I didn't notice before: append the variable name after the type: /** * @var bool $mIsPrintable */ If this doesn't break auto-suggesting in common IDEs (which IDEs does the average MediaWiki dev use?), this would be a nice workaround.
(In reply to comment #4) > If this doesn't break auto-suggesting in common IDEs (which IDEs does the > average MediaWiki dev use?), this would be a nice workaround. I use NetBeans and I know a couple of other people who do. I know there's a couple of phpStorm users out there, and I wouldn't be surprised if we've got a few people using Eclipse as well.
(In reply to comment #5) > (In reply to comment #4) > > If this doesn't break auto-suggesting in common IDEs (which IDEs does the > > average MediaWiki dev use?), this would be a nice workaround. > > I use NetBeans and I know a couple of other people who do. I know there's a > couple of phpStorm users out there, and I wouldn't be surprised if we've got a > few people using Eclipse as well. I've tried NetBeans, phpStorm, Eclipse (with PDT) and phpDocumentor. The auto-suggesting in all four works as it should when appending the variable name to the @var declaration. I think it might be a good idea to use this format in all php files.
We have since applied this filter and it is working as intended. Though I discovered a few bugs in the regex promoted on stackoverflow[1], we can fix those. Closing as fixed. It is unlikely to get fixed upstream seeing the flow of the report[2] [1] http://stackoverflow.com/a/8472180/319266 [2] https://bugzilla.gnome.org/show_bug.cgi?id=626105
