Improve engine API documentation

[utensil]

This is the PR for #80, not ready for merge yet, created for inspection.

[utensil]

Status update:

• Rework most of the doc of Network and NuPIC
• First pass on Region doc improvement

@rhyolight , the changes in the latest commits are substantially, and I'm requesting you (or invite other members such as @subutai ) to pre-review the changes, and asking the approval to keep on going this way.

The non-trivial changes are:

• Grouped methods using the Member Groups feature provided by Doxygen, and name the group as close as possible to the original grouping comments
• During grouping, though I avoided the relocating of methods, some reorder has been done
• Introduced some neat Doxygen tags:
  • @name, @{ and @} for grouping
  • @a for referencing arguments
  • @c for referencing types
  • @param[out] for output parameter
  • @code{.cpp} for showing example code snippets in doc
  • @note for noting
  • @todo for marking todos and generate todo list
  • @internal for preventing some outdated comment to show at the doc
• Enforced the following Doxgen styles(or convention):
  • doc for @param and @returns may not end with period
  • doc for @param and @returns must start at another line, precedent by spaces, to prettify the comment
• Filled in most of the document previously marked as TODO by reading the implmentation.

Please focus on the diff of these commits to get a better idea.

B.t.w. There're really many parameter types in Region... 😉

[rhyolight]

This is great. Can I merge this or are you still working on it?

[utensil]

The doc for NuPIC, Network, Region is completed except for a few marked todo question and ready to merge as long as there's no -1.

You may merge this PR to give everyone a taste. And I'll keep working on the rest of the docs on the same branch.

[rhyolight]

I don't think anyone is going to disagree with better docs, so here we go! 😄