Documentation Improvements

[JaffaKetchup]

Hi all,

As discussed in #927 (comment), this PR (when it's ready) will aim to improve the documentation currently available in flutter_map.

As also discussed, this is for many reasons:

• Some documentation is missing
  • This StackOverflow question
  • Add Polygons drawing #77
  • Fill closed Polyline with different color than border #972 (comment)
  • Please add screenshots to readme.md #971
  • What's the recommended way to make plugins? #895 (comment)
  • https://github.com/fleaflet/flutter_map/projects/1#card-24327391: none of these seem to still exist
  • There is not a single point in the README that mentions the MapController()
  • There is no mention on how to build good plugins and use the plugin API
  • and many more closed issues that could've been fixed much quicker by better API documentation
• Some documentation is old/could be improved
  • According to this page, the README has only been changed around 65 times compared to the 612 commits in total
  • Some of those were just adding plugins, or fixing minor mistakes
• The API documentation is lacking
  • On pub.dev, 10 points have been lost due to lack of 'dartdoc' compatible documentation: only 18.3% of public API elements have documentation
  • The auto generated docs look relatively empty compared to a package (that I understand is much bigger) that has 16 of the 22 public API elements documented; so where do people go to find out what something does?

Fixing the documentation will cause a massive reduction in issues both here on GitHub and on StackOverflow.

It will also give plugin owners a bit more space to describe what they're plugin does and what problems it can help solve, rather than being shoved down to the bottom of the README.

Contribution to the docs is greatly appreciated, just PR on my fork to add to the docs.

Thanks all (especially contributors and maintainers) for this great package!

[JaffaKetchup]

Temporarily paused.
Please see #927 (reply in thread)

[JaffaKetchup]

Closed whilst it's decided what to do in #927 (reply in thread).
Unless maintainers choose GitHub Pages option, this won't be reopened.

[JaffaKetchup]

Please see #992