Feature Request: Switch to JSDoc @license tags

[rpatterson]

For JavaScript files, switch from the simple double slash // SPDX-... comment format to the multi-line style /* ... */ comment format with the JSDoc @license tag for better cooperation with other tools.

I've tested it locally and this multi-line style with the JSDoc tag is already validated successfully by $ reuse lint, so this support would only need to be added to $ reuse annotate, though that's almost certainly the more difficult part.

Maybe also do this or some equivalent for TypeScript files.

[rpatterson]

Currently I have to manage the headers for my *.js files manually, so it would be nice to be able to automate this.

[BigBlueHat]

@rpatterson would using a template work for this use case?

[rpatterson]

@rpatterson would using a template work for this use case?

Probably, but I would consider that a workaround for this issue, not a solution. Its better to think of this as a matter of reuse honoring best practices for each language it supports. JavaScript has existing conventions and tooling for specifying the license in source files and reuse should honor those when adding license headers.

[seabass-labrax]

I'm generally in favour of having tools that work with each other, and so adopting the JSDoc conventions seems like a good idea. However, there a couple of things that might complicate matters:

• How should downstream consumers of the file know that the SPDX License List is being referred to? The JSDoc webpage that you linked to only suggests to "consider using the appropriate identifier" from the SPDX License List, but doesn't declare this as a requirement. Something like @license GPL-3.0-or-later is hardly going to be misunderstood, but something like @license MIT could potentially be ambiguous. Whilst feeling somewhat redundant, a line such as @license SPDX-License-Identifier: MIT could be one way to resolve this.

• JavaScript files are used in different contexts, but should the JSDoc be used in all cases? For instance, many projects contain JavaScript or JSX source code which is later transpiled, bundled or undergoes some other transformation as part of a build system. In other words, a given *.js file could function either as source code or as an executable binary (and that's before you get into WASM :grinning:).

[rpatterson]

However, there a couple of things that might complicate matters:

All good considerations that I'm not really qualified to weigh in on.

• How should downstream consumers of the file know that the SPDX License List is being referred to? The JSDoc webpage that you linked to only suggests to "consider using the appropriate identifier" from the SPDX License List, but doesn't declare this as a requirement. Something like @license GPL-3.0-or-later is hardly going to be misunderstood, but something like @license MIT could potentially be ambiguous. Whilst feeling somewhat redundant, a line such as @license SPDX-License-Identifier: MIT could be one way to resolve this.

To my ears, that sounds like a further refinement that's not necessary to just have the annotate sub-command add headers that are compliant with both reuse and JSDoc. IOW, not a bad idea to work out at some point but IMO not worth blocking this more narrow feature request.

• JavaScript files are used in different contexts, but should the JSDoc be used in all cases? For instance, many projects contain JavaScript or JSX source code which is later transpiled, bundled or undergoes some other transformation as part of a build system. In other words, a given *.js file could function either as source code or as an executable binary (and that's before you get into WASM 😀).

I don't have sufficient experience to weigh in on those other contexts, but again to my ears this sounds like further refinement that doesn't block this. Particularly when it comes to build system artifacts I think we're already well outside the use case for the annotate sub-command. IOW, I think it's reasonable to say that the annotate sub-command is for human developers writing original source code and that build systems are free to add required license headers for built artifacts in whatever way is best for the build system and that may not be using the annotate sub-command.

Put another way, I can't think of a case where using the annotate sub-command to add // SPDX-... headers would be worse if it added multi-line JSDoc /* ... */ headers and that starting there is better than it is now.