jashkenas / jashkenas/coffeescript
Bug: Block comments should be placed above variable assignment, not declaration (Fix JSDoc etc)
- Dominant language
- CoffeeScript
- Stars
- 16.6k
- Forks
- 2k
- PR merge metrics
- No merged PRs in 30d
Description
### Input Code
For example, if you want to output usable JSDoc to integrate with TypeScript:
```coffee
###*
# @param a {string}
###
method1 = (a) ->
###*
# @param b {string}
###
method2 = (b) ->
```
### Expected Behavior
```js
var method1, method2;
/**
* @param a {string}
*/
method1 = function(a) {};
/**
* @param b {string}
*/
method2 = function(b) {};
```
### Current Behavior
```js
/**
* @param a {string}
*/
/**
* @param b {string}
*/
var method1, method2;
method1 = function(a) {};
method2 = function(b) {};
```
### Possible Solution
Possible current workaround (pretty ugly):
```coffee
method1 = method2 = null
#
###*
# @param a {string}
###
method1 = (a) ->
#
###*
# @param b {string}
###
method2 = (b) ->
```
Alternatively, you can of course do inline typed params
```coffee
method1 = (###* @type string ### b) ->
```
but this is not always a feasible solution of course
### Context
Besides, should we maybe update the docs to state the possiblity of type-checking via JSDoc+TS? I know there is a TypeScript discussion issue going on in #5307 but this jsdoc thing is *already* possible.
* How has this issue affected you? What are you trying to accomplish? *
I am currently exploring building a basic CS LSP implementation based on piping CS compiler output to TSC, bundled in a VSCode extension. It works pretty well so far, I'll post in the other thread soon (edit: POC / WIP [here](https://github.com/phil294/coffeesense)
Contributor guide
Research direction
Start by reproducing the CoffeeScript input and comparing the current JavaScript output with the expected output shown in the issue. Trace how block comments and variable assignments are handled during compilation, then add coverage for the JSDoc example and confirm comments are emitted above their assignments without breaking other comment cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- coffeescript, javascript, typescript
- Domain
- compilers
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100