I'd like to keep my usage documenation in a readme file (duh) instead of comments at the top of my script. How do I get RDoc::usage to pull the usage information out of the readme instead of the script comments?
RDoc is designed to parse a source file, look at the comments and their locations, build cross-references of the variables, and, when done, tie it all into a decent output. Because RDoc is designed to work against source files it might not be the best choice for what you want to do.
Instead you might want to look into Yard, which is tag-based. Can I get my README.textile into my RDoc with proper formatting? has some useful information for you too.
In either case, if you can't get the app to parse a README-type doc like you want, you might be able to spoof it by putting all your docs in the file, along with class and method stubs so the parsers can grab the parameters, globals, and other "whatnot" they need to create usable documentation.
Otherwise, you'll probably have to forgo using the automated help and type it all in.
My recommendation is to do it the RDoc way, and document inside your code. It's not hard to do at all, and the output can be very satisfactory. It's pretty amazing how good a job RDoc can do.
I'm certainly not experienced enough to tell you the answer, but please allow me one piece of advice.
Most of the developers are unlikely to ever update the documentation even if it's 3 lines of code above the implementation.
Do a favor and don't make the process even harder.
Keeping general documentation separate is a nice idea though, but it has nothing to do in your RDoc-generated output anyway.
Related
I want to store brief snippets of code in the database (following a standard signature) and "inject" them at runtime. One way would be using eval(my_code). Is there some way to debug the injected code using breakpoints, etc? (I'm using Rubymine)
I'm aware I can just log to console, etc, but I'd prefer IDE-style debugging if possible.
Hm. Let's analyze your question. Firstly, it does not seem to have anything to do with databases: You simply store a code block in the source form somewhere. It can be a file, or a database. Secondly, you don't want IDE-style "debugging", but TDD-style. (But don't concentrate on that question now.)
What you need, is assertions about your code. That is, you need to describe what output should your code produce given some input examples. And then, you need to run that code and see whether its function matches the expectations. Furthermore, if you are not sure about the source of your snippets, run them in a sandbox (with $SAFE = 4). If your code fails the expectations, raise nice errors (TypeError, or even better, your custom made exception), and then you can eg. rescue those exceptions and eg. use some default code snippets...
... but maybe I'm not actually answering the same question that you are asking. If that's the case, then let me share one link to this sourcify gem, which let's you know the source, so that you can insert a breakpoint by saying eg. require 'rdebug' in the middle of code, or can even convert code to sexps. That's all I know.
Is there a tool that parses a Ruby script (MRI/YARV) and gives statistics of how many lines each module/class/method definition is?
Saikuro will do this. It's also included in metric_fu, which makes it easy to run Saikuro and many other code metrics tools.
(Be careful, the saikuro gem is probably not what you want, instead it's Saikuro with a capital "S".)
What do you mean by MRI/YARV? A script doesn't have an implementation associated with it. The tool may be associated with a particular implementation, though.
There may be such a tool in the code metrics section of Ruby Toolbox.
A parser I'm looking for should:
be Ruby parsing friendly,
be elegant by rule design,
produce user friendly parsing errors,
user documentation should be available in volume more than a calculator example,
UPD: allowing to omit optional whitespaces writing a grammar.
Fast parsing is not an important feature.
I tried Citrus but the lack of documentation and need to specify every space in rules just turned me away from it.
Treetop
Ragel
Or in case you want to parse Ruby itself:
parse_tree and ruby_parser
Edit:
I just saw your last comment about needing a subset of Ruby for your project, in that case I'd also recommend having a look at tinyrb.
I need a good reference for how to use standard Libraries in Ruby. Current libraries do not describe or give examples like say Java's. Yet this is where examples are much more needed (in Ruby), because I am not familiar with what the called method will yield! I am left with having to look at the source files every time, which seems inefficient. What is a good standard library reference... or am I just not understanding blocks yet?
I find myself bouncing around between the ruby core API on ruby-doc.org, googling for answers on random blogs, and spending time testing ideas in the interactive interpreter (irb). I haven't seen any other core reference documentation that I liked, but I do have a copy of The Ruby Way and its pretty decent.
Betweeen these four sources I can almost always find out how to solve the problem I'm working on.
Best of luck - ruby is fun, frustrating, and powerful.
There is the Ruby Standard Library documentation and sites like apidock. The Pickaxe book has a great reference towards the end. There's even a free version online, but it's quite out of date; to find the reference there, click Standard Library in the top-left frame.
Try GotAPI You'll be able to find the Ruby standard documentation and a whole lot of api docs there
Understanding blocks is pretty important, especially if you want to understand the Enumerable module. ruby-doc.org is usually all I need, but if I need a little more explanation I grab the PickAxe. You need the PickAxe, no question.
I am sorry , but again, i have to recommend ruby cookbook. (Already two times today)
This doesn't have to be Java, but it's what I'm dealing with. Also, not so much concerned with the methods and details of those, I'm wondering about the overall class file.
What are some of the things I really need to have in my comments for a given class file? At my corporation, the only things I really can come up with:
Copyright/License
A description of what the class does
A last modified date?
Is there anything else which should be provided?
One logical thing I've heard is to keep authors out of the header because it's redundant with the information already being provided via source control.
Update:
JavaDoc can be assumed here, but I'm really more concerned about the details of what's good to include content-wise, whether it's definitive meta-data that can be mined, or the more loose, WHY etc...
One logical thing I've heard is to keep authors out of the header because it's redundant
with the information already being provided via source control.
also last modified date is redundant
I use a small set of documentation patterns:
always documenting about thread-safety
always documenting immutability
javadoc with examples
#Deprecation with WHY and HOW to replace the annotated element
keeping comments at minimum
No to the "last modified date" - that belongs in source control too.
The other two are fine. Basically concentrate on the useful text - what the class does, any caveats around thread safety, expected usage etc.
Implementation comments should usually be about why you're doing something non-obvious - and should therefore be rare. (For instance, it could be because some API behaves in an unusual way, or because there's a useful shortcut you can use but which isn't immediately obvious.)
For the sanity of yourself and future developers, you really ought to be writing Javadocs.
When you feel the need to write comments to explain what some code does, improve the readability of the code, so that comments are not needed. You can do that by renaming methods/fields/classes to have more meaningful names, and by splitting larger methods into smaller methods using the composed method pattern.
If even after all your efforts the code is not self-explanatory, for example the reason why some unobvious code had to be written is not clear from the code, then apologize by writing comments. (Sometimes you can document the reasons by writing a test which will fail, if somebody changes the unobvious-but-correct code to do the obvious-but-wrong thing. But having a comment in addition to that is also useful. I prefix such comments often with "// HACK:" or "// XXX:".)
An overall description of the purpose of the class, a description for each field and a contract for each method. Javadoc format works well.
If you assign ownership of components to particular developers or teams, owners should be recorded in the component source or VCS metadata.