Add missing timeout implementation from #61 and fixed #72 (missing fl…

…ow-control setting in tests) (#74)

* fix test_low_level_api() by actually disabling flow control

This test routine claimed in a comment to disable flow control. It
actually requires the serial port to be transparent for all 256 byte
values, which in turn requires deactivation of software flow control,
because otherwise the byte-transparency tests fail for bytes 0x11
(Ctrl-Q, XON) and 0x13 (Ctrl-S, XOFF) on systems such as Ubuntu Linux
where software flow control is active by default.

* completed read/write timeout implementation in high-level API

Added new functions to set and clear cumulative timeouts for blocking
read and write functions, a new `Timeout` exception that will be
thrown, and time-tracking code in calls to the blocking read/write
functions. This way, users can now set overall timeouts on other IO
functions, such as `readuntil`, that make multiple calls to our
blocking functions.

* change close(::SerialPort) to return nothing

That what other close(::IO) methods in Base do. It looks quite odd in the
REPL to get the entire closed SerialPort object thrown back at you.

* build HTML documentation using Documenter.jl

also polished some docstrings and fixed a parameter name inconsistency

* split low-level API into separate module (#68)

The low-level API wrappers now sit in a submodule LibSerialPort.Lib.

The high-level API currently still re-exports a few symbols from that
low-level API module, to preserve backwards compatibility.

This is due to

* my previously started attempt to merge the low and high-level
  APIs for the three functions sp_flush, sp_drain, and sp_output_waiting

* the fact that several high-level APIs currently still refer to
  enum types and constants defined by the low-level API

We may want to phase out either or both in future, for a cleaner
separation, and a more Julian high-level API.

* documentation typo fixed

* allow arm64 to fail

Arm64 builds have long filed, therefore let's allow them to fail in Travis until that problem is fixed, such that PR authors for other issues do not get build errors that they are not responsible for.

.gitignore

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

.travis.yml

@@ -13,9 +13,10 @@ julia:
   - 1.4
   - 1.5
   - nightly
-matrix:
+jobs:
   allow_failures:
     - julia: nightly
+    - arch: arm64
   exclude:
     - os: osx
       arch: x86
@@ -25,6 +26,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,8 @@
+using Documenter, LibSerialPort, LibSerialPort.Lib
+
+makedocs(
+    sitename="LibSerialPort.jl",
+    format = Documenter.HTML(
+        prettyurls = get(ENV, "CI", nothing) == "true"
+    )
+)

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 repeat the documentation 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...)
+```

docs/src/wrap.md

@@ -0,0 +1,5 @@
+# Low-level C API wrappers
+
+```@autodocs
+Modules = [LibSerialPort.Lib]
+```