search

jeremyckahn / shifty

The fastest TypeScript animation engine on the web
https://jeremyckahn.github.io/shifty/doc/
MIT License
1.54k stars 88 forks source link

Remove exclamation marks from comment blocks #84

Closed ABM-Dan closed 8 years ago

ABM-Dan commented 8 years ago

Considering how thislibrary is distributed when minified, it doesn't make much sense for all the jsdoc comment blocks to use /*!, can we please remove them so more minifiers will work properly?

jeremyckahn commented 8 years ago

Hi @ABM-Dan, thanks for filing this ticket. The /!* blocks are necessary to prevent yuidoc from rendering private function annotation blocks. I'm not sure how else this might be handled. Do you have any suggestions?

ABM-Dan commented 8 years ago

No clue to be honest, but this is possibly the only js library that I know of to behave like this, have you investigated other libraries for similar approaches?

ABM-Dan commented 8 years ago

Maybe using @private ?

jeremyckahn commented 8 years ago

We can't use @private, because then those functions will show up in the "private" section of the generated docs, which is not preferable. Probably the easiest thing to do is replace the @ annotations with # or something else that YUIDoc doesn't recognize. Can you use the dist files in your build process in the meantime?

ABM-Dan commented 8 years ago

YUIDoc says

Indicates a member that should not be used externally. Although YUIDoc does not generate documentation for @private blocks, YUIDoc comments are still a nice, structured way to document internals in source code. All methods and properties are assumed to be public unless marked as private or protected.

Did you test it already? Does it indeed create an empty mention?

jeremyckahn commented 8 years ago

Oh hey! That works out nicely. What I mentioned about rendering the @private methods was something I was recalling from memory, so I could be wrong. If it's as simple as switching to @private, then so much the better. I'll test this out when I have a little time — if it works, I'll convert the annotations.

ABM-Dan commented 8 years ago

Let's hope it does :)

jeremyckahn commented 8 years ago

@ABM-Dan, please review the referenced PR. If it looks good to you, I will build it into a new release.

ABM-Dan commented 8 years ago

This is pretty much perfect.

jeremyckahn commented 8 years ago

Great! I should have a chance to put together a new release in the next day or two.

ABM-Dan commented 8 years ago

It didn't wreck the API tho, right?

P.S.: I mean the API docs.

jeremyckahn commented 8 years ago

No, it seems to be working just fine. I think I was incorrectly recalling a quirk about the documentation tool that I was using before YUIDoc. YUIDoc is much better!

jeremyckahn commented 8 years ago

Released as 1.5.2. Thanks again for reporting!

ABM-Dan commented 8 years ago

No, thank you!