Documentation for @commitlint/format does not match function

[bartvanandel]

The current documentation for @commitlint/format is still using the old report parameter format which was in use until commit c964696. The old behavior is still used pretty much verbatim in a non-exported function named formatResult, which is actually pretty useful by itself as the output of lint(message) still uses the same format.

Note that there are more pieces of documentation which need an update, e.g. the reference API documentation is also outdated.

Expected Behavior

• Documentation for @commitlint/format should match actual function signature

• @commitlint/format/formatResult function is useful and should be exported, so the output of lint can be easily formatted.

Current Behavior

• Documentation does not match function signature

• formatResult is not exported, there is only the default which requires a full report as input
• Output of lint can only be formatted by wrapping the parameter in an awkward way:

  const message = ...
  lint(message)
    .then(results => format({ results: [results] })
    .then(console.log);

Affected packages

• cli
• core
• prompt
• config-angular
• config-conventional
• docs

Context

The issue affects us because we use this formatting function in our build pipeline automation. We are currently using the workaround described above, but it's not as neat as it can be. And the only way to actually find out how to use format properly was to view the source code, the docs didn't help.

Your Environment

Executable	Version
commitlint --version	7.5.0
git --version	2.20.1.windows.1
node --version	v10.15.1

[byCedric]

Hi @bartvanandel, I can only apologise sorry for the changes! I'll make some time available upcoming Wednesday to update the documentation and export the method you described. I totally agree with you that you should also be able to format a single "result".

@marionebl @escapedcat do correct us if you think that function needs to stay hidden!

[byCedric]

Hmm, looks like this change actually has some additional implications. I think this needs to be addressed first. I'll update the documentation in a separate PR to get that updated ASAP.