Re: @augments/extends - Error: Missing dependency

[Michael Mathews]

Hello,

It might be useful if you were to describe what you would expect JSDoc to display in the output, given your example case: An `@extends foo` tag is encountered but nothing is known about foo, while the "lenient" flag is true.

Michael Mathews
mic...@gmail.com

On 13 Aug 2012, at 14:40, Michal Karwacki <mic...@krwck.com> wrote:

Hi!

My confusion around @extends is somewhat similar to the one in topics:
https://groups.google.com/forum/?fromgroups#!searchin/jsdoc-users/extends/jsdoc-users/xswTP1ufZMM/ih4DlOHsppgJ
https://groups.google.com/forum/?fromgroups#!searchin/jsdoc-users/extends/jsdoc-users/WKlVz5iAKLY/zRQX96pjyiUJ
except that this time I just don't want to document the methods of parent that I am extending from...

I am using Backbone.js but not require.js. What I need is only to show that my object extends the Backbone.Model for instance.
Getting the exception: "exception from uncaught JavaScript throw: Error: Missing dependency: Backbone.Model" is quite clear to me, although it is strange that the "--lenient" command line switch does not work. It always throws the exception and stops generating docs, but as per the "--help" command, it should generate the docs anyway, even with errors.

In other words - I think that this should be considered as a warning and continue the docs generation process, in contradiction to exception which stops the whole generation. I neither want to add a mock JSDoc for Backbone model in my code, nor do I want to eliminate all those @extends from my files.

Is this a bug? The "-l" not working?
Are there any patterns for forcing inheritance documentation without throwing the exception or printing parent's methods?

Cheers!
M.

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/ahpZ-Mkwy-YJ.
To post to this group, send email to jsdoc...@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.

[Michal Karwacki]

Hi again!

I would expect behavior similar to the one JSDoc 2 (jsdoc-toolkit) is presenting, i.e. just printing the name of the extended object/class/module without necessarily making 'foo' to be obligatory defined and existing somewhere in the documented code or JSDoc.

More specific example:https://gist.github.com/3341683
The JSDoc 3 output is correct, but it ignores @extends tag.

If I change @name Foo to @class/@constructor Foo it throws the exception and stops processing regardless of lenient flag. In all those cases the 'extends' information on template is not shown/available. It should at least make use of the '-l' flag and ignore the missing dependency, continuing with docs generation, shouldn't it? Like in the @name case.

If not a bug, isn't it inconsistent anyway?

Thanks again && cheers!
M.

PS. The exception is raised on line 323 of jsdoc.js.
PS2. There were situations while documenting projects with JSDoc 2, when I had to make mock JSDoc definitions just to provide some base for the following objects, but I think that providing it now for extended classes/objects could be quite troublesome in a project with many dependencies that I do not need to document myself.

[Michael Mathews]

Hello,

This is getting muddled. If there is a bug about the lenient mode, please create a ticket for this in the issue tracker.

This discussion should be limited to what you are proposing to be displayed in the docs if you are extending an unknown symbol. Sounds like your answer is, "just printing the name of the extended object/class/module." You can create a ticket for that change in the issue tracker too actually, because that makes sense to me.

Michael Mathews
mic...@gmail.com

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/WGGXQGLGfFQJ.

[Michal Karwacki]

Thank a lot!

So I will stop muddling, since I just got the answer I was asking for :) I just didn't know were to start and if my issue is worth tracking,
So I will track both items now.

Thanks a lot.
Cheers.

[Michael]

I should thank you, Michal. We depend on contributions from our users to make JSDoc better. Next, I'll pester you to submit a pull request; you have been warned. :)

Regards,

Michael

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/RUX1jzB4VyQJ.