Upgrade yard-doctest dependency

[blowmage]

The yard-doctest gem is used to test the code examples in documentation.
Upgrade the dependency to include the ability read .yardopts and exclude files.
Add the yard rake task to CI and enable yard documentation warnings.
Include a couple small documentation fixes as well.

[closes #2293, #2296, #2299, #2301, #2314, #2324, #2326, #2329]

[quartzmo]

I pulled the branch, ran bundle update, then removed existing doc directories. In handwritten libs such as google-cloud-bigquery, I see no warnings. However, in the generated libs that I tried I see warnings:

Chriss-iMac:google-cloud-dataproc quartzmo$ bundle exec rake yard
[error]: Error loading plugin 'yard-doctest'
[warn]: The proxy Google::Cloud::Dataproc::V1::ClusterControllerClient::OperationsClient.self has not yet been recognized.
If this class/method is part of your source tree, this will affect your documentation results.
You can correct this issue by loading the source file for this object before `lib/google/cloud/dataproc/v1/cluster_controller_client.rb'

[warn]: The proxy Google::Cloud::Dataproc::V1::ClusterControllerClient::OperationsClient.self has not yet been recognized.
If this class/method is part of your source tree, this will affect your documentation results.
You can correct this issue by loading the source file for this object before `lib/google/cloud/dataproc/v1/cluster_controller_client.rb'

[warn]: In file `lib/google/cloud/dataproc/v1/doc/google/longrunning/operations.rb':51: Cannot resolve link to Google::Longrunning::Operations::GetOperation from text:
	...{Google::Longrunning::Operations::GetOperation Operations::GetOperation}...
[warn]: In file `lib/google/cloud/dataproc/v1/doc/google/longrunning/operations.rb':57: Cannot resolve link to Google::Longrunning::Operations::ListOperations from text:
	...{Google::Longrunning::Operations::ListOperations Operations::ListOperations}...
[warn]: In file `lib/google/cloud/dataproc/v1/doc/google/longrunning/operations.rb':72: Cannot resolve link to Google::Longrunning::Operations::ListOperations from text:
	...{Google::Longrunning::Operations::ListOperations Operations::ListOperations}...
[warn]: In file `lib/google/cloud/dataproc/v1/doc/google/longrunning/operations.rb':81: Cannot resolve link to Google::Longrunning::Operations::CancelOperation from text:
	...{Google::Longrunning::Operations::CancelOperation Operations::CancelOperation}...
[warn]: In file `lib/google/cloud/dataproc/v1/doc/google/longrunning/operations.rb':87: Cannot resolve link to Google::Longrunning::Operations::DeleteOperation from text:
	...{Google::Longrunning::Operations::DeleteOperation Operations::DeleteOperation}...
Files:          14
Modules:        18 (   10 undocumented)
Classes:        55 (    1 undocumented)
Constants:      60 (    9 undocumented)
Attributes:    103 (    0 undocumented)
Methods:        18 (    0 undocumented)
 92.13% documented

[quartzmo]

And:

Chriss-iMac:google-cloud-dataproc quartzmo$ bundle exec rake doctest
[error]: Error loading plugin 'yard-doctest'
The google-cloud-dataproc gem does not have doctest tests.

[blowmage]

I didn't update the GAPIC-generated gems to fail on YARD warnings, only the veneer gems. But I don't see any warnings on dataproc, nor do i see the warning on CircleCI or Kokoro.

[blowmage]

I should clarify, I don't see any warnings in the ci output.

[quartzmo]

Hmm, I also do not see the warnings on rake ci. What happens to them?

Chriss-iMac:google-cloud-dataproc quartzmo$ bundle exec rake ci
[error]: Error loading plugin 'yard-doctest'

######################################
### BUILDING google-cloud-dataproc ###
######################################
...

bundle exec rake doctest
[error]: Error loading plugin 'yard-doctest'
The google-cloud-dataproc gem does not have doctest tests.

[quartzmo]

nm, I get it, rake ci only runs rake doctest, not rake yard.

[quartzmo]

I don't think this PR should close issues such as #2297 (and similar), since it does not resolve the YARD warnings, which can still be seen when running rake yard for these gems.

[blowmage]

The following veneer gems still have documentation warnings, and are being allowed to raise documentation warnings because their warnings are still unaddressed:

• Bigtable
• Datastore
• Error Reporting
• Firestore
• Logging
• Spanner
• Vision

[blowmage]

This PR isn't closing #2297, or any other generated gem. It is only closing hand-written gems that no longer have warnings.

[quartzmo]

@blowmage There's nothing we can do in generated gems to prevent this error, is there?

[error]: Error loading plugin 'yard-doctest'

[quartzmo]

So great to be able to use the latest yard-doctest releases! Bravo @blowmage!!!

[blowmage]

@quartzmo to get rid of that error locally, run this:

$ rm -rf ~/.yard/