"Working with custom formatters" page is out of date

[not-an-aardvark]

I noticed a few problems when reading through the "Working with custom formatters" page in our documentation.

• The fixableWarningCount and fixableErrorCount properties aren't included in the results objects, and they aren't described in the section below. (This was an oversight from when the properties were added in f5a7e42#diff-885d4b90cffa47361b72fc3c446d912a.)

• The example formatters have patterns like this:

  module.exports = function(results) {
      var results = results || [];
      // ...
  }

  However, the results array should never be null, so there is no need to redeclare the variable with a default like that.

• Several of the example formatters use console.log to output results, which is not recommended (since it doesn't work when the formatter is used by an integration). Instead, formatters should return a string.

• The example here for "Using a JSON formatter first" is unnecessarily complicated -- I don't think we need to walk people through how to create a separate script that reads from stdin. Also, we can tell people to use the built-in json formatter rather than creating their own custom formatter that does the same thing.

[platinumazure]

I've gone ahead and marked this as "good first issue" in case any new contributors want to take this on.

Prospective contributors: Please don't feel like you need to solve all of the issues at once. You are more than welcome to solve 1 or 2 of the issues identified above. Just make sure your commit summary ends with "(refs #9950)" instead of fixes in that case, so the issue stays open when we merge your pull request. Please stop by our Gitter chat with any questions. Thanks!

[dominictwlee]

Hi, if no one else is working on this I'd like to give it a go! I'm new to this but I'll read through the contributing guidelines thoroughly and make sure I'm helping out rather than causing a hindrance. I reckon i could look into in the next couple of days.

[Hirse]

With the @dominictwlee's PR merged, is this issue solved?

[not-an-aardvark]

I think most of the bullet points have been addressed, with the exception of the last bullet point.

[marla294]

Hi, I'm also new.... would like to take on that last bullet point. Will shoot for completion by the end of the week at the latest (7/13/18). LMK if any issues with this. Thanks!

[platinumazure]

Hi @marla294, please feel free to jump in! I look forward to your PR 😄

[marla294]

@platinumazure Thanks! I'll do my best!

[ViggoV]

The docs say that the filePath is supposed to be relative to the working directory. In my case however, they are absolute relative to the system root. I have reported an issue: #11156