Description: ------------ Okay, I know this is kind of "out there," but... It would be really handy to allow @param inside page level docblocks. In large files in large projects, it's helpful to reduce memory consumption by placing the guts of functions inside included files. main.php -------- function somefunc($data) { include 'somefunc.php'; } somefunc.php ------------ /** * @param array $data */ print_r($data);

If you're going to put PARAM tags in the page-level doc, I assume that means you only have ONE function in that file, correct? Even if page-level docblocks would accept PARAM tags, you still have to have a second docblock representing the function definition itself. What do you gain by putting your PARAM tags in the one page-level docblock instead of the one function-level docblock? For what you're wanting to do, it seems to me that what you really want to do is allow the page-level docblock to ALSO be the function-level docblock. That kind of "maybe I belong to this, or maybe I belong to that" mentality would I think seriously complicate the life of the page-level docblock... think about how many OTHER kinds of docblocks exist that it would ALSO have to consider itself belonging to. If I was in the situation of having individual functions per file, like you're describing, I would just utilize the function-level docblock for all my function-related tags. I'd stick to using my page-level docblock to make it clear that it (the file) only contained one method related to a specific class or package.

Before I get into replying, I thought of an additional reason to allow @param in file level docblocks: the file may be a shell script that takes command line arguments. @param's are the perfect way to document them. Yes, our files contain one one function per file. As far as your comment saying "you still have to have a second docblock representing the function definition itself" that's not true. In our system, we generally don't document the method definitions. This significantly reduces the size of our class files. Plus, it's nice to have the docblock in the file where the code resides so everything can be seen in one place. I'm not proposing that the file docblock be superimposed to the method docblock. Just that the @param's be allowed in file level docblocks. Thanks.

Bitten by the CAPTCHA! After my comment yesterday, I realized your example showed the function definition block in the original main.php file instead of somefunc.php, so I made another comment retracting that part about the function-level docblock. I THOUGHT that comment submitted successfully... apparently not ;) Regarding the shell script usage, now you're getting out of PHP. Although I do utilize the page-level docblocks in non-PHP files (js, css, htm), I do accept that PhpDocumentor should limit its own complexity by not trying to grow into managing other kinds of code and their specific needs... I therefore stick to using PhpDoc against non-PHP files ONLY when it works BY COINCIDENCE rather than by purpose. I've been toying with several ideas that might handle your specific need, using existing functionality. Is this what you want your output to look like: --------------------------------------------------------- /main.php Description a main function list file Functions somefunc (line 7) void somefunc ( $data) * $data --------------------------------------------------------- --------------------------------------------------------- /somefunc.php Description the guts of somefunc($data) - param array $data the data array arg --------------------------------------------------------- If this is what you want, try using this page-level docblock for somefunc.php: --------------------------------------------------------- <?php /** * the guts of somefunc($data) * - param array $data the data array arg * @package BugReport **/ print_r($data); ?> --------------------------------------------------------- This allows the somefunc PAGE to show the parameter listing, which I think is what you're specifically after. Although you stated you don't document your function definitions, you're still going to see the function listing in the file containing the function declaration (main.php in this case). Since there is NOTHING in the output linking the somefunc function listing on main.php's page to the somefunc.php page, I personally would at least put a "@see somefunc.php" or "@uses somefunc.php" tag in a block around the function definition in main.php, so that you'd have a link directly to your somefunc.php file available right there where somefunc() function is listed. Further, using the "@uses" tag will cause the somefunc.php file to show "@usedby" tags linking back to all the functions that used that file. In your case, that might always be a one-to-one relationship, but if I had a dozen function definitions that were all really skeletons pointing to other "guts" files, then more than likely I'd structure my "guts" files such that they could each be reused in many functions... and that would be a one-to-many relationship that would make the "@usedby" tags very handy. Here's what I mean: --------------------------------------------------------- /main.php Description a main function list file Functions somefunc (line 10) * uses: somefunc.php void somefunc ( $data) * $data --------------------------------------------------------- --------------------------------------------------------- /somefunc.php Description the guts of somefunc($data) * param array $data the data array arg * usedby: somefunc() --------------------------------------------------------- Both the "uses: somefunc.php" and "usedby: somefunc()" are hyperlinks back to each other's pages. Would this cover your need?

> I realized your example showed the function > definition block in the original main.php file > instead of somefunc.php Umm, you mean the inverse: the docblock is in somefunc.php. :) > Regarding the shell script usage, now you're > getting out of PHP. No. When I said "shell scrips" I meant PHP scripts meant to be called from a command line. You know: something like this: php parse.php file_param_in.txt file_param_out.txt > Since there is NOTHING in the output linking > the somefunc function listing on main.php's page > to the somefunc.php page, I personally would at > least put a "@see somefunc.php" or "@uses somefunc.php" Yeah. I know what you mean. Sometimes we do that. Your mentioning that brings up my proposal for a @usedby tag (see Bug 7297). Regarding your idea of my documenting the parameters using list elements (+, -, etc) instead of @param tags. While that would allow parameter documentation to be rendered, it's sub-optimal. The elements are parameters so people should be able to document them using @param and have the rendered documentation show them in the standard parameter format.

Ahh, the "terminology" chess match... my move ;) My "function definition block" meant the actual "function somefunc ($data) {}" code block... not an actual docblock. Again, the way I'd document that code structure myself would be with a function-level docblock around the function definition code block in main.php. I follow you now on "shell script". Having a command-line PHP script to be documented looks to me like an even better reason for page-level param tags than the original need (given my inclination to document the function via a function-level docblock back in main.php... again, "my inclination"). So, I reckon' we'll keep this one open as a feature request for the future. In the meantime, I hope the simple list feature can get you by.

This will introduce ambiguity - the fact that you two are arguing proves my point. No @param for command-line arguments. Another solution that resolves the ambiguity could be considered, but I want to avoid tag bloat if possible, so suggestions are appreciated. One possibility I have considered is allowing "sub-tags" @param:commandline @param:function something along those lines

That subtags idea looks reasonable to me. Are you thinking those would replace the plain PARAM tag, or be available in addition to the "legacy" PARAM tag (which itself would default to being a param:function tag)?

> This will introduce ambiguity What's ambiguous? Parameters are parameters. I don't understand the motive behind denying users the flexibility to use phpDocumentor in a way that helps them. > the fact that you two are arguing proves > my point. This point is unclear to me. > No @param for command-line arguments. But they are parameters. And you're considering a variant there of to document them.

@param:whatever would be in addition to @param

Dan, @param has been used for function parameters since the beginning of time (well almost). Changing the defition to include *file* parameters introduces ambiguity (my point) and will not happen. Adding another way of documenting this is fine, I set this to feedback to ask about @param:file as an alternative

I disagree about the ambiguity (but you already realize that) :). As far as making some sort of sub-tag, that's better than nothing.

Hi, I use PHP for shell scripting and I do agree with danielc. params (and return) exist in PHP files, when you invoke PHP code you do start with 'naked' file level code. It would be nice to document parameters (and return values) wherever they are using the same syntax.

@param would be nice, not only for shell args, but for used _REQUEST variables too ... currently i use @uses $_REQUEST['var'] @uses $_SERVER['PHP_SELF'] at least for $_REQUEST variables @param would be more meaningful for variables used in included scripts comming from outside i would also use @uses, in my cases i use: @uses $GLOBALS['some_resource'] and of course have the above variable documented with @global

No more feature work on phpDocumentor 1.x. Check out the new phpDocumentor 2.x (http://www.phpdoc.org/).