Consider including rule descriptions in docs

[jhauberg]

Consider the scenario where you just got a violation on something, but you don't fully understand what it's all about just by reading the description shown in the Xcode bubble.

You go to the docs and search for a substring of what you saw in the bubble. But. This might not net you any results, because the wordings are different on the docs site. You'd have to go deeper in the build logs to find the exact rule name, and that would net you the proper result. The problem is that that's not what you do; you search for the text you see immediately.

So we could improve the docs site by including the rule description (possibly followed by a deeper explanation). One issue is that these would have to be kept in sync. We might be able to extend the build script to parse rules and grab descriptions.

[jhauberg]

So as of 8f38003 the build script has access to all Rule objects and could theoretically easily put in descriptions.

However, one thing I've realized is that these descriptions are actually not very suited for this case. A lot of them have descriptions that expect additional information/formatting to be useful.

For example, take no-redundant-name:

Parameter \'{param}\' should not be named identically to its type \'{type}\'

Maybe that's totally fine and better than not having it at all?

The worst one is definitely no-todo:

TODO: {todo}

I suppose we could of course just choose to not include it for certain rules.

[jhauberg]

Closing for now.