jashkenas / jashkenas/coffeescript

Bug: Block comments should be placed above variable assignment, not declaration (Fix JSDoc etc)

Open
#5,366 9 comments 1 reaction 0 assignees View on GitHub
bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.