用于npm的包。我发现了两种方法(在阅读这段对话后):

  "devDependencies": {
    "del-comment": [
      "some-text"
    ],
    "del": "^5.1.0 ! inner comment",
    "envify-comment": [
      "some-text"
    ],
    "envify": "4.1.0 ! inner comment"
  }

但是在更新或重新安装带有“——save”或“——save-dev”的包时，会出现“^4.1.0 !”注释”中相应的地方将被删除。所有这些都将打破npm审计。

因为大多数开发人员都熟悉基于标记/注释的文档，所以我开始使用的约定是类似的。来尝尝:

{
  "@comment dependencies": [
    "These are the comments for the `dependencies` section.",
    "The name of the section being commented is included in the key after the `@comment` 'annotation'/'tag' to ensure the keys are unique.",
    "That is, using just \"@comment\" would not be sufficient to keep keys unique if you need to add another comment at the same level.",
    "Because JSON doesn't allow a multi-line string or understand a line continuation operator/character, just use an array for each line of the comment.",
    "Since this is embedded in JSON, the keys should be unique.",
    "Otherwise JSON validators, such as ones built into IDEs, will complain.",
    "Or some tools, such as running `npm install something --save`, will rewrite the `package.json` file but with duplicate keys removed.",
    "",
    "@package react - Using an `@package` 'annotation` could be how you add comments specific to particular packages."
  ],
  "dependencies": {
    ...
  },
  "@comment scripts": {
    "build": "This comment is about the build script.",
    "start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "test": "This comment is about the test script.",
  },
  "scripts": {
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

注意:对于dependencies、devDependencies等部分，注释注释不能直接添加到配置对象中各个包依赖项的上面，因为npm期望键是npm包的名称。这就是@comment依赖的原因。

我喜欢在JSON中添加注释的注释/标记样式，因为@符号与普通声明不同。

年长的建议

以下是我之前的建议。它内联注释的脚本，但我已经意识到，这些注释显示为“命令”在一些工具(在VS Code > Explorer > NPM脚本部分)。最新的建议没有受到这个问题的影响，但是脚本注释不再位于同一位置。

{
  "@comment dependencies": [
    ...
  ],
  "dependencies": {
    ...
  },
  "scripts": {
    "@comment build": "This comment is about the build script.",
    "build": "...",

    "@comment start": [
      "This comment is about the `start` script.",
      "It is wrapped in an array to allow line formatting.",
      "When using npm, as opposed to yarn, to run the script, be sure to add ` -- ` before adding the options.",
      "",
      "@option {number} --port - The port the server should listen on."
    ],
    "start": "...",

    "@comment test": "This comment is about the test script.",
    "test": "..."
  }
}

注意:在某些情况下，例如在“scripts”对象中，一些编辑器/ ide可能会抱怨数组。在脚本上下文中，VS Code期望值为字符串——而不是数组。

在浪费了一个小时的复杂和俗套的解决方案后，我找到了注释package.json中庞大的依赖项部分的简单而有效的解决方案。就像这样:

{
  "name": "package name",
  "version": "1.0",
  "description": "package description",
  "scripts": {
    "start": "npm install && node server.js"
  },
  "scriptsComments": {
    "start": "Runs development build on a local server configured by server.js"
  },
  "dependencies": {
    "ajv": "^5.2.2"
  },
  "dependenciesComments": {
    "ajv": "JSON-Schema Validator for validation of API data"
  }
}

当以同样的方式排序时，现在我很容易在Git提交差异中或在编辑器中跟踪这些依赖/注释对，同时使用package.json文件。

不需要使用额外的工具，只需要简单有效的JSON。

我有一个有趣的黑客想法。

创建一个适当的npm包名，作为文件包中的依赖项和devDependencies块的注释分隔符。Json，例如x----x----x

{
    "name": "app-name",
    "dependencies": {
        "x----x----x": "this is the first line of a comment",
        "babel-cli": "6.x.x",
        "babel-core": "6.x.x",
        "x----x----x": "this is the second line of a comment",
        "knex": "^0.11.1",
        "mocha": "1.20.1",
        "x----x----x": "*"
    }
}

注意:您必须在最后一个注释分隔行中添加一个有效的版本，如块中的*。

我做了一些你们可能会喜欢的事情:

这个//在名字里面意味着它是我的注释:

  "//":"Main and typings are used till ES5",
  "//main": "build/index",
  "//typings": "build/index",

受这条线索的启发，下面是我们正在使用的:

{
  "//dependencies": {
    "crypto-exchange": "Unified exchange API"
  },
  "dependencies": {
    "crypto-exchange": "^2.3.3"
  },
  "//devDependencies": {
    "chai": "Assertions",
    "mocha": "Unit testing framwork",
    "sinon": "Spies, Stubs, Mocks",
    "supertest": "Test requests"
  },
  "devDependencies": {
    "chai": "^4.1.2",
    "mocha": "^4.0.1",
    "sinon": "^4.1.3",
    "supertest": "^3.0.0"
  }
}