%doc uses RPM_DOC_DIR, which itself is set to $RPM_BUILD_DIR/%{_docdir} with %{_docdir} being set to %{_defaultdocdir}. Now, %{_defaultdocdir} is a setting, which reflects the [possibly relocated] situation on the building system. It should instead use something, which is based on the local %{prefix} variable of the spec file actually processed. I would propose declaring an additional local spec file variable named %{docdir} [without leading ``_''], which is initialized by the same algorithm as %{_docdir}, but as a function of %{prefix} and not as a function of %{_prefix} [, which %{_defaultdocdir} normally is]. A temporary workaround, for the time till being fixed in rpm itself, is to put a line %define _docdir %{prefix}/doc into the spec files. May be, it would be wise to take the opportunity and look for some other variables, which are also conceptionally to be well distinguished from their underscored counterparts.
No, %_prefix is the path, while %prefix is the side effect macro from Prefix: /usr and the two have different meanings and uses. While I agree the distinction is confusing to packagers, there's simply no way to undo the legacy without creating Yet More Confusion.