[Question] Documenting fictive or external methods/classes (ex: configatron)

[noraj]

Context

For configuration I use configatron gem in my project.

Questions

How can I use YARD to properly document config parameter from configatron directly in my source code? (because configatron does not appear as a class or a method)

More generally, is there a way to document fictive or external ruby methods/classes?

Workaround

The workaround I'm using right now is to create a makrdown file pages/CONFIGURATION.md, document it in pure markdown, and then in my code refer to it with a YARD file link{file:pages/CONFIGURATION.md Configuration}.

Workaround Issue

But even this workaround is not suitable and show a second issue with YARD file link.

Linking Files with {file:...} is a problem for markdown file because you can only provide an alias but not anchors as for HTML files.

{file:docs/GettingStarted.md Getting Started}
{file:mypage.html Name#anchor}

So you can't use something like {file:pages/CONFIGURATION.md Configuration#anchor_id}. Because if I set 200 parameters with configatron and I'm not able to refer to anchors in my markdown file people reading the documentation will be lost.

More questions

If there are no proper way to document fictive or external ruby methods/classes, do I need to open an issue for this?

Do I need to open an issue for YARD file link {file:} not supporting anchors for markdown files?

Environment details:

• OS: Manjaro
• Ruby version (ruby -v): ruby 2.4.1p111 (2017-03-22 revision 58053) [x86_64-linux]
• YARD version (yard -v): yard 0.9.12
• Relevant software dependency/versions:
  • configatron version: 4.5.1

I have read the Contributing Guide.

[lsegal]

Do I need to open an issue for YARD file link {file:} not supporting anchors for markdown files?

You can use {file:pages/CONFIGURATION.md#anchorhere Configuration} just fine unless I'm missing something. The anchor goes on the first token, the second+ tokens are for the link title only, not href.

If there are no proper way to document fictive or external ruby methods/classes, do I need to open an issue for this?

There are many. You can use the @!parse directive, the @!method or @!attribute directives, or even just write a real Ruby file that only gets loaded up by YARD when it parses source.

As far as documenting configuration from configatron, there are lots of different ways to do this, and the answer depends very much on what kind of information you're trying to expose. You could write a YARD extension to parse assignments against configatron.* and add them to some form of doc, but you still don't have anything to attach these docs to; configatron itself might be a method, but all of its state is stored in a runtime object, and those are fundamentally undocumentable.

If you want a design opinion, the abstractions provided by configatron should not be leaking to users of your library. I think the inability to document your config is one of many symptoms of this leaky abstraction. You are turning a transitive dependency into a direct dependency on your users, and in turn, forcing yourself to document that third-party library for your users. What you should be doing IMHO is wrapping configatron's API into your own (the Adapter pattern). Not only does this allow you to keep configuration docs within your own API (it solves this issue), it also allows you to avoid breaking downstream users if you ever decided to move away from a lib like configatron. Consider:

configatron.NVDFeedScraper.feed.default_storage_location = '/tmp'

class NVDFeedScraper
  # @!attribute default_storage_location
  #   @!scope class
  #   @return [String] the default location for feed data. Defaults to `/tmp`.
  class Feed
    def self.default_storage_location
      configatron.NVDFeedScraper.feed.default_storage_location
    end

    def self.default_storage_location=(v)
      configatron.NVDFeedScraper.feed.default_storage_location = v
    end
  end
end

This will get documented as a class attribute on NVDFeedScraper::Feed. This also means users have an explicit reference on how to modify this configuration without understanding another library.

And then, if you wanted to, you could at any point in the future transparently move away from configatron on the backend with a simple code swap:

class NVDFeedScraper
  class Feed
    class << self
      # @return [String] the default location for feed data. Defaults to `/tmp`.
      attr_accessor :default_storage_location
    end
    @default_storage_location = '/tmp'
  end
end

Hope that helps!

[noraj]

You can use {file:pages/CONFIGURATION.md#anchorhere Configuration} just fine unless I'm missing something. The anchor goes on the first token, the second+ tokens are for the link title only, not href.

My bad, the doc was confusing, so this is in an error in the doc? {file:mypage.html Name#anchor} should be {file:mypage.html#anchor Name} right? Here is the short PR: #1154

There are many. You can use the @!parse directive, the @!method or @!attribute directives, or even just write a real Ruby file that only gets loaded up by YARD when it parses source.

I read the documentation of @!parse @!method or @!attribute directives but I didn't understand very well how to use them.

If you want a design opinion, the abstractions provided by configatron should not be leaking to users of your library. I think the inability to document your config is one of many symptoms of this leaky abstraction. You are turning a transitive dependency into a direct dependency on your users, and in turn, forcing yourself to document that third-party library for your users. What you should be doing IMHO is wrapping configatron's API into your own (the Adapter pattern). Not only does this allow you to keep configuration docs within your own API (it solves this issue), it also allows you to avoid breaking downstream users if you ever decided to move away from a lib like configatron. Consider:

This is a very good advice, thanks.

Hope that helps!

That helps a lot, thank you again.