Adding extra jdoc tags about brackets-funcdocr

[Wikunia]

Hey,

sorry for my late response :/ Can you provide a simple example?

[yuretz]

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.

[Wikunia]

Hmm thanks, yeah I think I will need some time to solve it. Thanks for the issue and stay tuned!

[Wikunia]

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.

[Wikunia]

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...

[yuretz]

Hi Wikunia,
Thanks for your replies. I'll definitely try it tomorrow. Would I be able to install it directly from the repo url?

[Wikunia]

Yes it is in the master branch

[yuretz]

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

• I place the cursor at the end of the line, after which I would like to add my new tag and hit 'enter' to add an empty line. If, for example, previous line was @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.
• I start typing @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.
• I manually delete indentation before @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:

1. Align the rest of the fields in columns by fields' relative position. Like, 1st field is always in the first column after the tag, 2nd is in the 2nd and so on. This one is probably the easiest option.
2. Align the rest of the fields in columns, taking into account the field purpose. Like, all names get their own separate column, all type names get their separate column, all textual descriptions too, and so on. This will probably look better, but might be more difficult to implement, and eats more screen space for indentation.

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?

[Wikunia]

Again version v0.8.27 ;) Would be great if you would install it from url!
Changes:

• The tags will be sorted now so @throws and @this will be shown at the top and not @author, when typing @th :D
• the wrong alignment on tabbing should be fixed now
• the cursor is aligned under [[Description]] and you include a @ tag it will be on the most left side

Thanks 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 ;)

[yuretz]

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.

[Wikunia]

Okay and then it will look like @throws {[[ExType]]} [[Description]] and ExType can be filled if the syntax throw new UserException("..."); is used right?

[yuretz]

Exactly!

[Wikunia]

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! ;)

[yuretz]

Sure, thank you!