# Rdoc, api + exceptions

**URL:** <https://www.ruby-forum.com/t/rdoc-api-exceptions/52841>\
**Category:** Ruby\
**Created:** [January 19, 2006, 6:06pm UTC](https://www.ruby-forum.com/t/rdoc-api-exceptions/52841 "2006-01-19T18:06:25Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![jonbaer](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/54ee81/32.png) [@jonbaer](https://www.ruby-forum.com/u/jonbaer)\
**Post date:** [January 19, 2006, 6:06pm UTC](https://www.ruby-forum.com/t/rdoc-api-exceptions/52841/1 "2006-01-19T18:06:25Z")

</div>

Hi,

Ive become a pretty big fan of Ruby in the past month during my time  
off and while going through PickAxe book and looking around Im not  
sure if im missing something fundamental about exceptions … (bare  
w/ me as I am a Java/PHP convert)

Normally when developing an API you can express what exceptions may  
occur when invoking a particular method …

public foobar() throws BadFooBarException

In Ruby, it would seem to me that nearly ~everything~ can throw at  
least one exception (or at least cause NameError), so Im wondering at  
least how you would document that your method should be placed in a  
begin/rescue/end block from a custom exception.

Thanks!

- Jon

---

<div class="post-metadata">

**Author:** ![jonbaer](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/54ee81/32.png) [@jonbaer](https://www.ruby-forum.com/u/jonbaer)\
**Post date:** [January 19, 2006, 9:13pm UTC](https://www.ruby-forum.com/t/rdoc-api-exceptions/52841/2 "2006-01-19T21:13:13Z")

</div>

jon baer wrote:

> Normally when developing an API you can express what exceptions may  
> occur when invoking a particular method …
> 
> public foobar() throws BadFooBarException
> 
> In Ruby, it would seem to me that nearly ~everything~ can throw at  
> least one exception (or at least cause NameError), so Im wondering at  
> least how you would document that your method should be placed in a  
> begin/rescue/end block from a custom exception.

I follow a simple rule when dealing with exceptions and it works equally  
well in Java or Ruby.

Every method has a purpose. If a method is unable to achieve its  
purpose, then it must fail (and indicate failure via an exception).

So when do you wrap a method in a begin/rescue clause? When the failure  
of a called method should not cause the failure of the calling method.  
Rescue the failure, attempt to fix it and continue.

When you think of the problem in terms of success/failure, then the type  
of failure is usually not important. This means you don’t (usually)  
have to worry about exactly which type of exception is being thrown and  
making sure you capture each and every possible exception type (which  
creates quite fragile programs IMHO).

–  
– Jim W.

---

<div class="post-metadata">

**Author:** ![jonbaer](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/j/54ee81/32.png) [@jonbaer](https://www.ruby-forum.com/u/jonbaer)\
**Post date:** [January 19, 2006, 9:55pm UTC](https://www.ruby-forum.com/t/rdoc-api-exceptions/52841/3 "2006-01-19T21:55:58Z")

</div>

I guess this stems from not having to “precompile” an app vs. only  
having the exception come up at runtime.

For example when using ActiveRecord for the first time I was unaware  
that a specific type of exception could occur based on a record not  
being located (which is obvious) but what type of exception I was  
expected to trap was not + only found during unit/web test.

It would be nice to have something equivalent to @throws in rdoc to highlight what might occur.
- Jon