build HTML documentation using Documenter.jl

also polished some docstrings and fixed a parameter name inconsistency

.gitignore

@@ -5,3 +5,4 @@ deps/*
 !deps/build.jl
 
 Manifest.toml
+docs/build/

.travis.yml

@@ -13,7 +13,7 @@ julia:
   - 1.4
   - 1.5
   - nightly
-matrix:
+jobs:
   allow_failures:
     - julia: nightly
   exclude:
@@ -25,6 +25,15 @@ matrix:
       arch: arm64
     - julia: nightly
       arch: arm64
+  include:
+    - stage: "Documentation"
+      julia: 1.5
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));
+                                               Pkg.instantiate()'
+        - julia --project=docs/ docs/make.jl
+      after_success: skip
 
 before_install:
   # - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo chmod 666 /dev/tty*; fi

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,3 @@
+using Documenter, LibSerialPort
+
+makedocs(sitename="LibSerialPort.jl")

docs/src/index.md

@@ -0,0 +1,78 @@
+# LibSerialPort.jl – access serial ports
+
+```@docs
+LibSerialPort
+```
+
+# Enumerating serial ports
+
+```@docs
+list_ports
+get_port_list
+print_port_metadata
+```
+
+## Opening and configuring ports
+
+```@docs
+LibSerialPort.open(::AbstractString, ::Integer)
+SerialPort(::AbstractString)
+open(::SerialPort; ::SPMode)
+close(sp::SerialPort)
+set_speed
+set_frame
+set_flow_control
+isopen(sp::SerialPort)
+eof(sp::SerialPort)
+seteof
+get_port_settings
+print_port_settings
+set_read_timeout
+set_write_timeout
+clear_read_timeout
+clear_write_timeout
+sp_flush
+sp_drain
+sp_output_waiting
+```
+
+# Read and write methods from Base
+
+Many of the read/write methods defined in `Base` that operate on an
+object of type `IO` can also be used with objects of type
+`SerialPort`. Therefore we repead the documentations of some of these
+here. (Note that some of the following docstings also refer to other
+methods that are not applicable to `SerialPort`.)
+
+```@docs
+Base.read(::IO, ::Any)
+Base.read!
+Base.readbytes!
+Base.readavailable
+Base.readline
+Base.readlines
+Base.eachline
+Base.write
+Base.print(::IO, ::Any)
+```
+
+# Additional read methods
+
+```@docs
+read(::SerialPort)
+nonblocking_read(::SerialPort)
+bytesavailable(::SerialPort)
+```
+
+# Other references
+
+The following are listed here only because they are referenced above:
+
+```@docs
+Base.ntoh
+Base.hton
+Base.ltoh
+Base.htol
+Base.stdout
+Base.string(xs...)
+```

src/LibSerialPort.jl

@@ -1,4 +1,32 @@
+"""
 
+The `LibSerialPort` module provides access to [serial
+ports](https://en.wikipedia.org/wiki/Serial_port)
+([UARTs](https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter)
+or USB/Bluetooth devices that emulate their operating-system
+interface) using the portable C library
+[libserialport](http://sigrok.org/wiki/Libserialport).
+
+It defines the `SerialPort` type, which is returned by
+`LibSerialPort.open`. This is a subtype of `Base.IO` and can
+therefore be used like a file handle, using many of the same `read`,
+`write`, `print`, etc. methods defined for `Base.IO`.
+
+# Example
+```
+using LibSerialPort
+
+list_ports()
+ports = get_port_list()
+
+sp = LibSerialPort.open("/dev/ttyUSB0", 115200)
+set_flow_control(sp)
+sp_flush(sp, SP_BUF_BOTH)
+write(sp, "hello\\n")
+println(readline(sp))
+close(sp)
+```
+"""
 module LibSerialPort
 
 using Libdl