Object files require a page level doc block #794

Closed
bkuhl opened this Issue Mar 31, 2013 · 6 comments

Projects

None yet

3 participants

@bkuhl
Contributor
bkuhl commented Mar 31, 2013

I am currently seeing a No short description for file Api/MissingParameterException.php for the below class. This is occurring because of the empty doc block. However if I do not include the empty doc block I get an error that this file has no page level doc block.

With the standard practice of having 1 class per file, what is the intended use for a page level doc block?

<?php

/**
 * 
 */
namespace MyNamespace\Api;

/**
 * A missing required parameter prevents the library from being able to make
 * an API call.
 *
 * @since 1.0
 */
class MissingParameterException extends \Exception {

}

Thanks for all that you guys do, this tool is awesome 👍

@boenrobot
Contributor

The "standard practice" is just that - a practice. It's not a requirement. You can have multiple documentable elements defined within the same file. The file comment serves to document what's the common thing between all documentable elements defined within the file.

The Responsive template doesn't display the file comment anywhere, although other templates like "New Black" do - in their "Files" section.

Now, you might be wondering "Why not just detect if there's only one documentable element, and assume this element's docblock is also the file level docblock if its the only documentable element?" - that's a little harder than it might seem, because in order to save memory, PhpDocumentor streams the files - PhpDocumentor doesn't know if there's one, two or more elements until the second element starts. At that point, all data associated with the first element has been removed from memory. It's only at a later stage that PhpDocumentor "remembers" how much elements there are - at that point, errors like missing doc comments and the like have already been reported.

Combine the above with the fact that there are some tags that can only be specified at a file level comment block, but not in a class/interface/trait level, and the problem of efficiently validating the contents of a doc block becomes even trickier.

It's not impossible to fix this problem, but making sure we fix it while also keeping PhpDocumentor memory efficient is the harder part.

@bkuhl
Contributor
bkuhl commented Apr 4, 2013

@boenrobot - Thanks for the detailed feedback. I'm particular about wanting to ensure the library I'm documenting is documented correctly and consistently. PHPDocv2's ability to report errors in documentation is a huge asset for this. However since I'm using the 1 class per file convention, the "page level doc block" errors can make it difficult to find actual errors in my documentation.

Is it possible to disable this error so that the error list is more useful to me?

@mvriel
Member
mvriel commented Apr 4, 2013

There is an open issue to implement such functionality: #40

@bkuhl
Contributor
bkuhl commented Apr 4, 2013

Excellent, thanks!

@mvriel
Member
mvriel commented Apr 30, 2013

@bkuhl since there is an open issue for fixing this item; is this issue resolved as far as you are concerned? If so I'd like to close it

@bkuhl
Contributor
bkuhl commented Apr 30, 2013

Yes, thanks!

@bkuhl bkuhl closed this Apr 30, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment