I felt like I wanted this some times, but always concluded that the "scripts" commands should be self-explanatory.
There are also plenty of metadata fields.
And for detailed descriptions, why not just but a README.md next to it?
I think here, D. Crockfords original motivation for not allowing comments in JSON pays off perfectly well. If package.json allowed comments, they'd already have been abused as metadata.
Also, as someone who sometimes has a hard time coding and naming things concise and to-the-point: there just should be no need for comments in this file.
I know what I'm looking for in there and in which fields. Comments would clutter the file and encourage silly comments such as "this command starts a local development server, compiles your code using HMR, writes its output in folder XY, listen on port Z, etc etc". This can go into a README. At best, the commands should be self-documenting.
This is a good example and I pondered it while writing the comment you replied to.
But my conclusion in this case is:
If there is some issue with breaking changes that prevents updating, or a deliberate decision for a certain version for a certain reason, it should be explained in a README and in the former case, the package manager should point out the conflicting dependencies in case you try to update.
I felt like I wanted this some times, but always concluded that the "scripts" commands should be self-explanatory.
There are also plenty of metadata fields.
And for detailed descriptions, why not just but a README.md next to it?
I think here, D. Crockfords original motivation for not allowing comments in JSON pays off perfectly well. If package.json allowed comments, they'd already have been abused as metadata.
Also, as someone who sometimes has a hard time coding and naming things concise and to-the-point: there just should be no need for comments in this file.
I know what I'm looking for in there and in which fields. Comments would clutter the file and encourage silly comments such as "this command starts a local development server, compiles your code using HMR, writes its output in folder XY, listen on port Z, etc etc". This can go into a README. At best, the commands should be self-documenting.