search

alexdalitz / dnsruby

Dnsruby is a feature-complete DNS(SEC) client for Ruby, as used by many of the world's largest DNS registries and the OpenDNSSEC project
Other
194 stars 77 forks source link

gemspec enhancement + yard support #159

Closed noraj closed 4 years ago

noraj commented 4 years ago
coveralls commented 4 years ago

Coverage Status

Coverage increased (+0.7%) to 77.641% when pulling f46560059e63af280e3cb3e8eafbd64f080268b3 on noraj:patch-2 into d81d2b590cb0278afc571e6086def8a61e61c3f1 on alexdalitz:master.

alexdalitz commented 4 years ago

Yo dude - thanks for all your PRs! I'm (sadly) afraid I don't know enough about YARD to deal with this one - could you please leave some comments? Thanks!

noraj commented 4 years ago

Yard is an enhancement of rdoc, the documentation you can see at rubydoc.info is generated with yard.

So https://www.rubydoc.info/gems/dnsruby/ is built with default yard option from the source of your project. If you want to serve the doc with yard options like adding extra pages you need to host it yourself somewhere else like I did for https://gitlab.com/noraj/nvd_api with the doc hosted on gitlab pages https://gitlab.com/noraj/nvd_api thans to Gitlab CI. It's possible to dothe same with GitHub pages and GitHub actions now.

Anyway YARD is mostly a superset of rdoc and is the new standard nowadays. So if you see nothing wrong at https://www.rubydoc.info/gems/dnsruby/ moving from rdoc to yard will be transparent.

noraj commented 4 years ago

And you can also include markdown or rdoc pages in YARD extra pages.

noraj commented 4 years ago

@alexdalitz see https://stackoverflow.com/questions/3699706/yard-is-not-the-same-as-rdoc In short you won't have to change a thing.

If you want an example of my code commented with yard see https://gitlab.com/noraj/nvd_api/blob/master/lib/nvd_feed_api.rb

See The getting started guide https://rubydoc.info/gems/yard/file/docs/GettingStarted.md

It the same but a lot simpler but it still keeps the old rdoc syntax to be backward compatible.

image

alexdalitz commented 4 years ago

Ok - thanks! I guess I'll give it a go ;) Thanks again for all your PRs and help!