Supports @throws tag

[alkar]

Exceptions are quite handy when working on a number of languages.

It is essential that those are documented, so a need arises.

[devinrhode2]

+1

[dnutels]

👍

[cedx]

Definitely a must-have!

[eschwartz]

Yes, please.

[herom]

+1 this would have a great impact on 'cross-language' documenting :)

[jksdua]

+1

[lexander]

Looks like there's some good support for this issue being implemented. In JS throw will always be a vanilla error object, would the tag need to support any other types for other languages?

[devinrhode2]

Throw may not always be an error object, it can be any type

throw 'problem'

throw callbackToReattemptFailedAction
On Jul 24, 2013 5:51 PM, "Alexander Shusta" notifications@github.com
wrote:

Looks like there's some good support for this issue being implemented. In
JS throw will always be a vanilla error object, would the tag need to
support any other types for other languages?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/135#issuecomment-21526923
.

[devinrhode2]

And in fact I was even recently considering using throw as an api

throw {returnValue: uniqueReturnValue};
On Jul 24, 2013 6:08 PM, "devin rhode" devinrhode2@gmail.com wrote:

Throw may not always be an error object, it can be any type

throw 'problem'

throw callbackToReattemptFailedAction
On Jul 24, 2013 5:51 PM, "Alexander Shusta" notifications@github.com
wrote:

Looks like there's some good support for this issue being implemented. In
JS throw will always be a vanilla error object, would the tag need to
support any other types for other languages?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/135#issuecomment-21526923
.

[jksdua]

I've created custom Error classes in my app such as MissingArgumentError, InvalidArgumentError, InternalError and have been using @throws like this:

@throws InvalidArgumentError If options are not provided, the function throws an error

[devinrhode2]

I also like to use custom error objects, a js guru describes how to make
them here:
http://www.nczonline.net/blog/2009/03/10/the-art-of-throwing-javascript-errors-part-2/

Not sure what to do with this info.. maybe yui just links that error type
to where the function is defined.. :?
On Jul 24, 2013 6:42 PM, "jksdua" notifications@github.com wrote:

I've created custom Error classes in my app such as MissingArgumentError,
InvalidArgumentError, InternalError and have been using @throwshttps://github.com/throwslike this:

@throws https://github.com/throws InvalidArgumentError If options are
not provided, the function throws an error

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/135#issuecomment-21528458
.

[lexander]

@devinrhode2 indeed, I actually realized this on the way home last night and then forgot to update my comment. Thanks for the link to the Zakas post.

So, the tag should definitely support arbitrary classes for the error types. And, we should link to the local class definition or out to the ECMA definition if the specified type is one of the 7 defined by ECMA-262 5th under sections 15.11.6.1-15.11.6.6 plus the top level Error class.

[devinrhode2]

Super official. I like it, but most people probably want to see the mdn
docs instead of the full spec, SyntaxError, for example
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError

I don't know what linking conventions yuidoc currently has, should probably
stick to those

On Jul 25, 2013 8:49 AM, "Alexander Shusta" notifications@github.com
wrote:

@devinrhode2 indeed, I actually realized this on the way home last night
and then forgot to update my comment. Thanks for the link to the Zakas post.

So, the tag should definitely support arbitrary classes for the error
types. And, we should link to the local class definition or out to the ECMA
definition if the specified type is one of the 7 defined by ECMA-262 5th
under sections 15.11.6.1-15.11.6.6 plus the top level Error class.

—
Reply to this email directly or view it on GitHub.

[alkar]

In PHP you can throw any class that extends the built-in Exception.
On Jul 25, 2013 6:57 PM, "Devin Rhode" notifications@github.com wrote:

Super official. I like it, but most people probably want to see the mdn
docs instead of the full spec, SyntaxError, for example

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError

I don't know what linking conventions yuidoc currently has, should
probably
stick to those

On Jul 25, 2013 8:49 AM, "Alexander Shusta" notifications@github.com
wrote:

@devinrhode2 indeed, I actually realized this on the way home last night
and then forgot to update my comment. Thanks for the link to the Zakas
post.

So, the tag should definitely support arbitrary classes for the error
types. And, we should link to the local class definition or out to the
ECMA
definition if the specified type is one of the 7 defined by ECMA-262 5th
under sections 15.11.6.1-15.11.6.6 plus the top level Error class.

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/135#issuecomment-21564021
.

[am17torres]

Does anyone know if there are workarounds to this, I have a method that must be implemented by a subclass, how do i indicate that.

[kcphysics]

Bump, I am working on a project and am liking YUIDoc, but it would be great if we could get this done.

Even something very simple would be nice, just a way to keep track and everything could be manual.

[caridy]

🎱

I'm waiting for a volunteer to submit a PR, if any of you can do it, I promise that we will clean it up and merge it. :)

[eschwartz]

I've had success using arbitrary annotations with YUIDoc. From my experience, just adding a @throws tag to a comment block will add it to the generated YUIDoc data.

For example:

/**
 * @method myMethod
 * @throws {CustomErrorType} Watch out for this error!
 */
var myMethod = function() {
  throw new CustomErrorType('You shouldn\'t have called this method. Shame on you.');
}

Then in your method.handlebaras partial template, you'll have access to a throws property, with a value of "{CustomErrorType} Watch out for this error!"

The only tricky bit is that you have to find a way to parse the error type, and link to the CustomErrorType docs page. Here are some handlebars helpers I put together that'll do just that.

So now you can do:

{{#if throws}}
  Throws:
  {{#eachTypeInText throws}}
    <a href="{{link}}">{{type}}</a>
  {{/eachTypeInText
{{/if}}

This will output:

Throws: {<a href="/classes/CustomErrorType.html">CustomErrorType</a>} Watch out for this error!  

You'll probably want to flesh out the type helpers to get it formatted how you want.

I hope this helps you out.

[dnutels]

More or less what I do with all "missing" tags. I customize all the templates anyway, since, really, with ALL the respect in the world, the default set of templates is, to put it mildly, lousy.

[apm]

@dnutels that's a fair comment, but antagonizing more than helpful. If everyone customizes the templates themselves for this sort of thing, yet doesn't help get their modifications in the mainline ---- well, a year goes by and the OP was never helped.

Same goes for the theme as a whole. I don't like the default much, but it is functional. It is complicated to modify the current theme in a non-trivial way, so I think that many keep the default even though they would prefer something else. If you have spent time creating a better theme, it would be nice to get your thoughts and maybe some code to improve the default.

[dnutels]

@apm Wasn't trying to be controversial, more approving of the above comment - since the solution (or rather a WA) involves template fiddling.

Can't share a specific theme, however.

[eschwartz]

The reason I chose YUIDoc over JSDoc was exactly because of this: the templates are very extensible, and you have (mostly) direct access to parsed annotation data. Non-trivial changes took a bit more work than I originally hoped, but overall I've been very happy with YUIDoc.

Rather than adding new annotations to YUIDoc, I would love to see improvements which make it easier in general to customize templates and annotations. For example, the proposed @throws annotation follows a common pattern:

/**
 * @tag {Type} name Description.
 */

As I mentioned, you can get the raw {Type} name Description string from within a template. But wouldn't it be nice if YUIDoc recognized the annotation pattern and parsed it for you as:

tag: {
  "name": "name",
  "type": "Type"
  "description": "Description."
}

Another use case I've thought of would be @resolvesWith and @rejectsWith annotations to use for methods which return Promise objects. I don't necessary think these should be added to YUIDoc, but I would love to be able to configure them as custom annotations in yuidoc.json.

@dnutels I'd really like to contribute some of these changes to the YUIDoc library -- maybe once we make it past some deadlines at my work. In the meantime, we're about to open source our library, including the YUIDoc themes. If you're interested, maybe I can get you early access.

[okuryu]

Thanks for your waiting. #305 is ready for review.

[herom]

awesome 👍 🎆