Newbie Questions

[Perry Smith]

I plan on trying yard probably later today or this week but wanted to ask a question at the same time.

The command line ruby script I'm working on loads files via require and some of those files execute at load time.  For example I have:

Item.add_filter("Alert", { level: 1 .. 10 }) do |context, item|
  context.output(item.to_text, [ :red ])
end

and this is not within a class or module.  I could put it inside a class or module and I could create a DSL and I might do that but right now, I just call class methods at load time.

I could not find any method of documenting this with rdoc.  What I do is I copy the file and munge it and then read the file as if it was a mark down file but I'd like to avoid that if possible.

The problem that rdoc has is it does not have a "container" to put the documentation in -- no class, module => no container.  Without a container, rdoc has no place to hook it into the tree of html pages.  Am I going to run into the same thing with yard?  If so, can I get some suggestions on how to work around it?

Thank you,
Perry

[Loren Segal]

Hey Perry,

To provide the best answer, it would be great to know what exactly you are trying to document with the block provided. YARD is optimized to primarily documents Ruby APIs, not UIs or CLI switches. Is "Alert" some kind of command line switch?

If your goal is to provide user documentation for your CLI options, I would recommend something like md2man[1] to write proper man pages, as is typically expected for CLIs. I'm not really sure what that block does, though. You could use YARD to forcibly define a method for that given block, but that only works if this functionality is exposed via a method in your API. Again, more context would be useful here.

Note that you *can* still do this with YARD even if it is a CLI thing (it is extensible enough to support the use case), but unless you're documenting a module, class, or method, you would likely need to write a plugin to make that work seamlessly.

Regards,

Loren

--

---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Perry Smith]

Well... this project is sort of a pipe dream that may not ever really happen.  There are multiple levels going on.

First, there is user documentation or what you would call CLI documentation.  Currently that is in the README and its focus is pretty direct.

The project is for a tool that we can use at work where "we" is about 100+ users -- all of them fairly smart and some of them capable programmers.  So the tool is infinitely customizable and that is the area where the add_filter can be used.  A user will be able to specify his own filters to fine tune how the tool works.  Part of that documentation is with the add_filter method.  But I also want them aware of the default rules; plus see examples of rules.

I listened to your talk last night from Ruby Conf 2011 and now that I pause, some of my desires can be accomplished with examples  which I've not used before.  But it would still be nice if, somewhere, the base default filters are described and documented, the logic of why they are there, and their objective.

The part that is a pipe dream is getting others to participate and add to the functionality.  But having good documentation of how to add to the tool is the first step in that goal.

[Loren Segal]

You can most certainly write tooling that auto-detects the usage of the add_filter calls and generates some kind of documentation for it. You can look at "writing a handler" article for some tips:

http://yardoc.org/guides/extending-yard/writing-handlers.html

Note that since publication, the "Legacy" mode is all but gone-- the article describes the current state of the art. You can use a handler + some code object creation (either a method, class, or even a custom object) to generate seamless documentation for those blocks.

You can even just use the handlers described above to generate a .md file or some database of your choosing that you then turn into some automated documentation on your own. In other words, every time you parse that block, you can write "Filter: X -- does Y and Z" into a file that then gets inserted as an extra file (.md). YARD is flexible in that way. You don't *have* to use the template generation portion for every customization.

Hope that helps,

Loren