Closed yuretz closed 7 years ago
Hey,
sorry for my late response :/ Can you provide a simple example?
Yes, sure.
Please see the image below:
So, what happens in this case, is that I'm wrapping the long line by hitting 'Enter' and then trying to re-indent it by hitting 'Tab'.
Maybe there were some other cases, when it behaved similarly, but right now I can't remember.
FuncDocr 0.8.26, Brackets 1.3
In the screen capture I forgot curly brackets around {Error}
, but it doesn't change the behavior anyway.
Hmm thanks, yeah I think I will need some time to solve it. Thanks for the issue and stay tuned!
Hi @yuretz
this one is the new version which isn't good as well :/
The problem is that I have a maximum padding which aligns the descriptions but probably you would like to see something like this?
Or the third option would be:
FYI the current implementation of @throws
is:
"throws": "@throws [[Description]]",
there is no name field for the name of the error.
Maybe you would like to test the newest version 0.8.27
(Install from url)
It's not perfect but unfortunately it is more complex than I thought of...
Hi Wikunia, Thanks for your replies. I'll definitely try it tomorrow. Would I be able to install it directly from the repo url?
Yes it is in the master branch
Hi again,
Thanks for the new version. It's really nice to see that small (but very useful) things like FuncDocr get their deal of support and attention!
I have tested the new version a little bit. It seems like it solves part of the issue, but not all of it. And you are probably right, this looks like a more complex general problem with manual editing of auto-generated comments.
When I add @throws
, or any other jsdoc tag after existing auto-generated tags, what I do is
@param {type} name description
, the cursor gets aligned with the description start on the previous line. And that's fine and totally make sense at this point.@throws
, auto-completion menu appears amd I choose @throws [[Description]]
template. It is inserted, but it stays aligned with the previous line description and that of course doesn't make sense anymore.@throws
to make it aligned properly with other tags and then hit 'Tab' to navigate to the missing [[Description]] placeholder, and the line gets wrongly re-aligned again.Regarding the solution, it's hard to tell which one is the best. There is no doubt that all @<tag_name>
parts should be aligned in the start. From there, as I see it, you have two options:
As for me, I could definitely live with any of those options implemented, as long as manual re-indentation is not necessary (or minimal) to make the jsdoc comment block look reasonable.
BTW, would it be possible to support both @throws
template with and without exception type included?
Again version v0.8.27 ;) Would be great if you would install it from url! Changes:
@throws
and @this
will be shown at the top and not @author
, when typing @th
:D[[Description]]
and you include a @
tag it will be on the most left sideThanks for your support.
With the current implementation two hints for @throws
aren't possible because I might want to use the number of [[...]]
for a specified tag for alignment which isn't easily possible with two different implementations for @throws
.
But I think @throws
should have always an exception type, right? Then it's better documented I think ;)
Hi, Thanks for the updated version. I'm testing it right now, and it looks good so far. I agree that having documentation with explicit exception types is much better than without them. I personally always use it with the type.
Okay and then it will look like @throws {[[ExType]]} [[Description]]
and ExType
can be filled if the syntax throw new UserException("...");
is used right?
Exactly!
Hi @yuretz , It's 2017 now and wow just read our small conversation again. Looks like I can close this issue, right? Otherwise just reopen it! ;)
Sure, thank you!
Hello, When I add extra jsdoc tags, for example
@throws {Error} Will throw if something is wrong
, the line sometimes gets indented wrong, so that@throws
is aligned with previous annotation description text. It seems it only happen if previous annotation text was wrapped. Is there a way to avoid this behavior? Right now I'm just manually re-indenting those lines, but it gets annoying pretty soon, so I decided to try and ask here :)Thanks!
BR, Yuriy