[DBIx-Class-Devel] Pull Request: topic/docs-pod-inherit

[Brendan Byrd]

On Tue, Dec 4, 2012 at 6:45 AM, Peter Rabbitson <rabbit+dbic at rabbit.us> wrote:
>
> I was actually going further - the skips should happen automatically,
> based solely on lack of POD on the other side. Think of it as
> "no_dead_links => 1" sort of thing. As an example see
> ResultSource::pk_depends_on(). Instead of fishing these out one by one,
> something like a Pod::Tree walk can populate a %seen and prune them
> automatically.

The new code found a bunch of these.  I also had to add detection
support for grandparent relationships.  (In other words, the method
was overloaded, but the documentation was not "overloaded".)  Still
need a new dead_links test for P:I, but this new version is mostly
ready.

One thing it did find was "discard_changes ($attrs?)", instead of
"discard_changes".  So, I'll scan through the debugs to find other
problems.

Here's the rest of the debugs, if anybody is interested:
https://gist.github.com/047a828e46e2f433a5f8

> Precisely. Here is an example:
> https://github.com/dbsrgits/dbix-class/blob/master/t/sqlmaker/bind_transport.t#L47
> Note all of these args are "advisory", i.e. a [ {} => $value ] will also
> work, it just won't do anything fancy.

I will try to allocate some tuits to write this section, especially
since most of the docs are in that commit.

>> " ( pending in the next patch: [ $val ] === [ {}, $val ] ) "
>>
>> Was this already implemented?
>>
>
> Sadly no, I ran out of tuits and never came back to it :( I *think* it is
> a little amount of code, but honestly I have not looked since.

Same here.  Sounds like a one-liner, but I'm not completely sure.

> Actually I misspoke here - PI should not create dead links period. It
> could list the inherited methods still perhaps under an optional
> include_undocumented_inherits => 1, but it should not generate links for
> them.

I think I have something that'll make everybody happy:

A string with the same format as C<method_format>.  This is the
string used for methods that don't exist in the inherited module's
documentation.  A blank string (C<''>) will remove any dead links.
The default is to not check for dead links.

This option typically only makes sense if C<method_format> is a
link, but it can be used to automatically remove undocumented
methods or present them in a different manner.

This feature requires L<Pod::Tree> to be installed.

> Speaking of PI fixes - I noticed that it recreates the entire directory
> structure in maint/.generated_pod, even if there was actually no POD to
> generate. Perhaps an over-eager mkpath() ?

Yes.  I moved the mkpath further down, after it's figured out if the
POD is needed or not.

-- 
Brendan Byrd <Perl at ResonatorSoft.org>
Brendan Byrd <BBYRD at CPAN.org>