Documentation bug: methods not in table of contents

[dsadinoff]

Not sure why, but in http://search.cpan.org/~jlmartin/Paws-0.31/lib/Paws/SQS.pm the ReceiveMessage method is documented in the body, but doesn't appear in the table of contents at the top of the file.

Also, this thing rocks. keep it up!

[pplu]

Hi!

Thanks for the report. It looks like search.cpan.org doesn't like some part of the POD that Paws generates. I think the problem is that search.cpan.org doesn't like methods with long titles, so it doesn't include them in the TOC. MetaCPAN does pick it up: https://metacpan.org/pod/Paws::SQS

Also look at: http://search.cpan.org/~jlmartin/Paws-0.31/lib/Paws/EC2.pm vs https://metacpan.org/pod/Paws::EC2 (displays same problem as you report).

If you can, I'd say you use metacpan.org whenever you can to view the docu, while we see what can (or can't be done).

I know that @karenetheridge knows lot about how this all works, as she maintains tons of critical distributions. Maybe she can advise if Paws is doing something not very compliant. @karenetheridge would you mind to share your knowledge, or point me to who can do so?

[dsadinoff]

Sounds like it may be a search.cpan.org bug after all. MetaCPAN works fine, as you indicate.

Other workaround: revert to using local generated manpages, which also don't lie to me :)

Thanks again!

[Grinnz]

I don't see anything particularly wrong with the formatting, but if you want to better support faulty pod parsers, you could wrap the =head2 lines on whitespace such as:

=head2 ReceiveMessage(QueueUrl => Str, [AttributeNames => ArrayRef[Str|Undef], MaxNumberOfMessages => Int, MessageAttributeNames => ArrayRef[Str|Undef], ReceiveRequestAttemptId => Str, VisibilityTimeout => Int, WaitTimeSeconds => Int])

=head2 ReceiveMessage(QueueUrl => Str, [AttributeNames => ArrayRef[Str|Undef], 
MaxNumberOfMessages => Int, MessageAttributeNames => ArrayRef[Str|Undef], 
ReceiveRequestAttemptId => Str, VisibilityTimeout => Int, WaitTimeSeconds => Int])

These two declarations would be equivalent, as long as there are no blank lines in between. search.cpan.org may still omit it from the table of contents, if it's simply leaving out headings that are too long. If that is the case there's not really anything you could do about it except contact the search.cpan.org maintainer - http://search.cpan.org/feedback

[pplu]

@Grinnz thanks! I've contacted the mail on the feedback page to see what help I can get

[karenetheridge]

Alternatively, you could shorten the headings... this might also improve readability:

- =head2 AddPermission(Actions => ArrayRef[Str|Undef], AWSAccountIds => ArrayRef[Str|Undef], Label => Str, QueueUrl => Str)
+ =head2 AddPermission
+
+    (Actions => ArrayRef[Str|Undef], AWSAccountIds => ArrayRef[Str|Undef], Label => Str, QueueUrl => Str)

[castaway]

I'm being sponsored by ZipRecruiter to have a go at improving the Paws documentation generation. This is one of the items on my list.

I would like to submit a patch which will split the listed method names as Karen suggests. This will make method names easier to find when glancing down the list, especially in the table of contents generated by metacpan/search.cpan.org

It looks like we just need to amend the service class template to achieve this.

[pplu]

Hi @castaway . That's great! Just to complete the status on this: when I said "I've contacted the mail on the feedback page to see what help I can get", but got no response back, so I have no further information on the cause that search.cpan.org doesn't display some methods in the TOC.

[pplu]

This will be fixed on the next CPAN release. I'll keep this issue open until it hits CPAN

[karenetheridge]

Looks like this made it into 0.37. thanks all!