Removes inline docs that are not updated/current

[peterramsing]

I've been pondering this for a while. As I've been working on more and more projects I've learned that the more documentation that is written the more that needs to be maintained. I think documentation is great! This documentation is just a duplicate of that documentation that is on the site, though–and I have not been maintaining it well.

Now, if someone wanted to work on having the inline docs create external docs, I'm all ears. There are people who are much better at that than I so I'm more than happy to receive outside input, here.

I'm creating a pull request for this to get some outside input on this and if there are any immediate objections to this. because these are not maintained something needs to happen as they are already causing me confusion and I've heard from others similarly. I don't want to maintain two sets of docs, though...

[peterramsing]

@codebysubtract Any thoughts on this?

[steve-holland]

@peterramsing I would agree, I think removing them at this point would be the best course of action. There's no benefit to having the documentation in two places, it's so easy to forget to update one or the other. I think my last commit highlights your point perfectly. I updated the comments in the code, but totally forgot the documentation that appears on the lostgrid.org site!

I'm not sure how useful it would be to have the docs autogenerated from the code comments because of the type of project LostGrid is. Had it been a library in which you call functions directly, then I would have leaned more towards autogeneration. However, because their direct use is sort of abstracted away, it's a less obvious place for documentation.

As an aside, I had a quick look at the autoprefixer code (being a quite popular Postcss lib) and they don't have the documentation in the code either. They favour small one line comments describing the actual code functionality as and where it happens rather than at the top if the file.