docs: fix some poor spelling & phrasing in docs

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

docs/building.md

@@ -3,16 +3,16 @@ Building libmraa                         {#building}
 
 libmraa uses cmake in order to make compilation relatively painless. Cmake runs
 build out of tree so the recommended way is to clone from git and make a build/
-directory.
+directory inside the clone directory.
 
 ## Build dependencies
 Not all these are required but if you're unsure of what you're doing this is
 what you'll need:
-* swig 3.0.4+
+* [SWIG](http://swig.org) 3.0.5+
-* git
+* [git](http://git-scm.com)
-* python 2.7 or 3.4+ (you'll need not just the interpreter but python-dev)
+* [python](http://python.org) 2.7 or 3.4+ (you'll need not just the interpreter but python-dev)
-* nodejs 0.10.x (you'll need not just the interneter but nodejs-dev)
+* [node.js](http://nodejs.org) 0.10.x (you'll need not just the interpreter but nodejs-dev)
-* cmake 2.8.8+
+* [CMake](http://cmake.org) 2.8.8+
 
 ## Basic build steps
 
@@ -31,46 +31,49 @@ got.
 
 Our cmake configure has a number of options, cmake-gui or ccmake (cmake -i is
 no longer with us :() can show you all the options. A few of the more common
-ones are listed below - note that when the option starts with CMAKE_ it's an
+ones are listed below. Note that when the option starts with CMAKE_ it's an
 option that is made available by cmake and will be similar in all cmake
 projects. You need to add them after `cmake` but before `..`.
 
 A few recommended options:
-Changing install path from /usr/local to /usr
+Changing install path from /usr/local to /usr:
  -DCMAKE_INSTALL_PREFIX:PATH=/usr
 
-Building debug build - adds -g and disables optimisations - this will force a full rebuild:
+Building debug build - adds -g and disables optimisations - this will force a
+full rebuild:
  -DCMAKE_BUILD_TYPE=DEBUG
 
 Using clang instead of gcc:
  -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
 
-Building with an older version of swig (swig < 3.0.2) requires the disabling of javascript:
+Building with an older version of SWIG (< 3.0.2) requires the disabling of javascript:
  -DBUILDSWIGNODE=OFF
 
-Disabling python module building
+Disabling python module building:
  -DBUILDSWIGPYTHON=OFF
 
-Building doc, this will require sphinx & doxygen
+Building doc, this will require [SPHINX](http://sphinx-doc.org) &
+[Doxygen](http://doxygen.org):
  -BUILDDOC=ON
 
-## Dependancies continued
+## Dependencies continued
 
-You'll need at least swig version 3.0.2 and we recommend 3.0.4 to build the
+You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the
 javascript & python modules. If your version of SWIG is older than this then
-please see below for disabling SWIGNODE otherwise you will get a weird build
+please see above for disabling SWIGNODE. Otherwise you will get a weird build
-failure when building the js module. The python module builds with swig 2.x.
+failure when building the javascript module. The python module builds with SWIG
+2.x.
 
-The basic build steps are as follow, we'll assume you're building from git,
+During the build, we'll assume you're building from git, note that if you
-note that if you compile with git installed your version of mraa will be tagged
+compile with git installed your version of mraa will be tagged -dirty. This
--dirty. This simply means git wasn't installed or that you where building form
+simply means git wasn't installed or that you where building form a tarball.
-a tarball. You can modify build/src/version.c before running make if this is
+You can modify build/src/version.c before running make if this is incorrect.
-incorrect. The instructions listed here all assume that build/ is an empty dir
+The instructions listed here all assume that build/ is an empty dir that lives
-that lives inside the cloned repository of mraa.
+inside the cloned repository of mraa.
 
 If you have multiple versions of python then mraa can get confused, we
 recommend using virtualenv to select which version of python you want. We test
-2.7 the most but swig will generate valid 3.x python code but we do not
+2.7 the most but SWIG will generate valid 3.x python code but we do not
 generally support building both at once.
 
 ## Using a yocto/oe toolchain

docs/debugging.md

@@ -1,30 +1,31 @@
 Debugging libmraa                         {#debugging}
 =================
 
-This page contains a few debugging tip, when filing an issue please go through
+This page contains a few debugging tip. When filing an issue please go through
-this list as if you don't it's the first thing we'll have to ask you to do.
+this list as it's the first thing we'll ask you to do.
 
-### Version
+### Finding your mraa version
 
 Getting the exact version of libmraa you're running is really important to us.
 The best way to get this is to call mraa_get_version() or mraa.getVersion(). If
 mraa returns x.x.x-dirty then your version was not built from a git tree or you
 built out of tree (see our building doc) - or you don't have git installed.
 
-### Syslog
+### Finding error logs
 
-mraa logs pretty much everything that goes wrong to syslog, these days it'll go
+mraa logs pretty much everything that goes wrong to syslog. These days it'll go
-to the systemd journal usually so check with `sudo journalctl -f` whilst
+to the systemd journal so check with `sudo journalctl -f` whilst running your
-running your app or check all libmraa messages with `journalctl -t libmraa`.
+app or check all libmraa messages with `journalctl -t libmraa`.  Grab all the
-Grab all the messages from the initialisation message right up to your last
+messages from the initialisation message right up to your last one. Using a
-one, using a pastebin is always a good idea, I like dpaste.com. If your system
+pastebin is always a good idea, I like dpaste.com. If your system does not have
-does not have systemd likely your log is in /var/log/messages or similar.
+systemd likely your log is in /var/log/messages or a similar location.
 
-### Common Errors
+### Common errors to check for
 
 * Not running as root
-* Incorrect IO numbers, mraa uses physical connector pin numbering see your
+* Incorrect IO pin numbers, mraa uses physical connector pin numbering see your
-  platform doc for details
+  platform documentation for details
-* Unsuported platform
+* Your platform is unsupported
-* Using the wrong pin, check pin capabilities
+* Using the wrong pin, check pin capabilities either using the API or your
+  platform documentation
 

docs/internals.md

@@ -14,13 +14,10 @@ confuse some, it's typically not an issue as platforms rarely expose more than
 one of these for user use and so when this is the case, libmraa will always use
 the bus in the pinmapper. For example edison uses i2c #6 but since there is
 only one, libmraa will try to be helpful and everything is treated as 6 when
-doing a mraa_i2c_init and so when this is the case, libmraa will always use the
+doing a mraa_i2c_init(). The _raw functions will override the pinmapper and can
-bus in the pinmapper. For example edison uses i2c #6 but since there is only
+be accessed without a valid board configuration. This can be helpful either in
-one, libmraa will try to be helpful and everything is treated as 6 when doing a
-mraa_i2c_init(). The _raw functions will override the pinmapper and can be
-accessed without a valid board configuration. This can be helpful either in
 development of platform configurations for mraa or when modifying kernels
-etc... The mechanism is used heavily internaly.
+etc... Internally the mechanism is used heavily.
 
 In libmraa, all code is split into 7 modules, src/{i2c, spi, gpio, uart, pwm,
 aio and common}. These should be fairly self explanatory in goals/purpose but a
@@ -52,10 +49,10 @@ also where platform hooks can be defined, functions that will be run at various
 
 The mraa_pininfo_t structure needs to be set for the board pincount (set in a
 macro in the platform configuration header. Every pin will have a
-mraa_pincapabilities_t which will define what it can do. The doxygen doc
+mraa_pincapabilities_t which will define what it can do. The doxygen
-explains how this works but it's essentially a bitfield which needs to be set
+documentation explains how this works but it's essentially a bitfield which
-for every capability the pin can have. Gpios can have multiple muxes which will
+needs to be set for every capability the pin can have. Gpios can have multiple
-be set at the gpio init before it can be toggled.
+muxes which will be set at the gpio init before it can be toggled.
 
 ### i2c ###
 
@@ -68,8 +65,9 @@ i2c/smbus.c. This library simply makes it easier for us to handle the error
 conditions that can arrise when writing on i2c buses. Essentially the API is
 fairly simple consisting of writes & reads.
 
-Careful - on alot of platforms i2cdetect will often crash, for finding your i2c
+Careful - on alot of platforms i2cdetect will often crash. To findi your i2c
-addresses please look at your sensors datasheet!
+addresses please look at your sensor's datasheet! If using i2cdetect most
+platforms do not support SMBus quick write so use the '-r' flag.
 
 ### spi ###
 
@@ -78,9 +76,9 @@ chip select from spidev. Spi(0) could lead to spidev5.1 and Spi(1) to
 spidev5.2. Typically on a micro using a random gpio as a chip select works
 well, and on some platforms if one is careful with threads this can work well
 with mraa. However when a kernel module shares the same bus as spidev (but on a
-different CS) this behaviour is *very* dangerous. Platforms such as galileo
+different CS) this behaviour is *very* dangerous. Platforms such as Galileo
-gen2 & edison + arduino breakout work this way. Mraa will not help you in using
+Gen2 & Edison + Arduino breakout board work this way. Mraa will not help you in
-a non HW chip select, do so at your own peril!
+using a non hardware chip select, do so at your own peril!
 
 ### gpio ###
 
@@ -100,9 +98,8 @@ definition.
 GPIOs are typically interfaced via sysfs because that's easier for us but we
 can also work with fast gpio. This is typically preffered to do mmap gpio
 access. This is however trickier and typically relies on lots of platform
-hooks. We do support by default to go hit /dev/mem or another device at
+hooks. By default we support hitting /dev/mem or another device at specific
-specific addresses to toggle gpios which is how mmap access works on some
+addresses to toggle gpios which is how mmap access works on some boards.
-boards.
 
 Note that in Linux gpios are numbered from ARCH_NR_GPIOS down. This means that
 if ARCH_NR_GPIOS is changed, the gpio numbering will change. In 3.18+ the
@@ -119,16 +116,16 @@ set the pinmapper correctly for uart to work on some platforms.
 
 ### aio ###
 
-AIO pins are numbered after GPIO pins. This means that on arduino style boards
+AIO pins are numbered after GPIO pins. This means that on Arduino style boards
 pin 14 is A0. Typically mraa will only support an ADC if a platform ships with
-one and has a good kernel module for it. extra i2c/spi ADCs can be supported
+one and has a good kernel module for it. Extra i2c/spi ADCs can be supported
 via something like UPM but are unlikely to receive support in mraa at the moment.
 
 Note that giving mraa_aio_init(0) will literally query the pinmapper for
 board->gpio_count + 0 so you must place your aio pins after gpio_count. This is
 the default behaviour but can of course be overriden by advance function
 pointers. Whilst maybe not the sanest of defaults, most of the hobbyist boards
-we deal with follow a similar naming pattern to arduino or have no ADC so for
+we deal with follow a naming pattern similar to Arduino or have no ADC so for
 now we have considered this sensible.
 
 ### Initialisation ###
@@ -136,13 +133,13 @@ now we have considered this sensible.
 mraa_init() needs to be called in order to initialise the platform files or
 'pinmap'. Because calling this is tedious libmraa uses a C constructor to run
 mraa_init on library load. This means that it is not possible to stop this
-running and all functino calls like mraa_set_log_level() will not work during
+running and all function calls like mraa_set_log_level() will not work during
-mraa_init(). This feature is supported by most sane compilers & libcs but you
+mraa_init(). This feature is supported by most sane compilers and libcs but you
 can turn off CTORS in uclibc, though I've yet to find a configuration with
 someone doing that. mraa_init() can be called multiple times if you feel like
 being 'safe'.
 
-In the SWIG modulse mraa_init() is called during the %init stage of the module
+In the SWIG modules mraa_init() is called during the %init stage of the module
 loading. This is simply to avoid mraa_init() running 'too' early, though I've
 never seen an issue in running it in a CTOR.
 
@@ -150,15 +147,15 @@ never seen an issue in running it in a CTOR.
 
 At the time when libmraa was created (still the case?) the only - working -
 API/wrapper generation tool that supported nodejs was SWIG. For more general
-information on swig please see the swig documentation.
+information on SWIG please see the SWIG documentation.
 
 The src/{javascript, python} & src/mraa.i folders contain all the files for the
-swig generation. The C++ headers in api/mraa/ are given as input sources to
+SWIG generation. The C++ headers in api/mraa/ are given as input sources to
 SWIG. SWIG modules do not link to libmraa (although maybe that would be a good
 idea...)
 
 Typemaps are used heavily to map uint8_t* pointers to bytearrays and
-node_buffers. These are native python & nodejs types that represent uint8_t
+node_buffers. These are native python & node.js types that represent uint8_t
 data the best and are very well supported in both languages. Argument
 conversions and memory allocations are performed so the performance of using
 these functions compared to the C/C++ equivalent will likely be a little lower,
@@ -172,7 +169,7 @@ array to generate a binding.gyp file from the skeleton binding.gyp.cmake in
 src/javascript. Because we don't expect most NPM users to have SWIG we
 precompile the src/mraajsJAVASCRIPT_wrap.cxx. The src/version.c is already
 known since this is a static tarball so we write that too. These files are
-placed not in a build/ dir but in the main mraa dir. You can then tar the dir
+placed not in a build/ directory but in the main mraa directory. You can then
-up and send it to NPM. This is done automatically on every commit by our
+tar the directory up and send it to NPM. This is done automatically on every
-automated build system.
+commit by our automated build system.
 

docs/npm.md

@@ -15,11 +15,11 @@ we have generated for you.
 Recreating tarball
 ------------------
 
-From a checkout of mraa you can do the following to 'generate' this tarball.
+You can run the following commands to 'generate' this tarball from a checkout
-It's important to not leave a .git directory as npm will then consider the
+of mraa.  It's important to not leave a .git directory as npm will then
-tarball contains a full git tree. Also you need a top level dir which matches
+consider the tarball contains a full git tree. You also you need a top level
-the npm pkg name so we create one with a symlink and add the 'h' flag to tar to
+dir which matches the npm pkg name so we create one with a symlink and add the
-follow simlinks.
+'h' flag to tar to follow symlinks.
 
 ~~~~~~~~~~~~~{.sh}
 mkdir build