I recently stepped upon a bug where an ebuild wanted to move documentation into /usr/share/doc/${P} Which is wrong. Documentation goes into /usr/share/doc/${PF} but that likely get's unnoticed, especially for packages that get upstream bumps often and rarely get -r1-versions in Gentoo. This could easily be checked with repoman. There should be no valid reason to ever use /usr/share/doc/${P} for anything, so if this string appears in an ebuild, it almost certainly is a bug.
repoman support has been removed per bug 835013. Please file a new bug (or, I suppose, reopen this one) if you feel this check is still applicable to pkgcheck and doesn't already exist.