feat: POC header comment API design (#332)

# Motivation

Inspired by #307, can we
design a nice API to read/write comments of header cards?

# Changes

* `write_key` takes either a simple value, or a tuple of (value,
comment) for writing comments
* `read_key` returns a new structured type which contains both the value
and comment
* tests and docs updated
* restructure the headers code
    * create new `headers` module with previous code
    * add `constants` module, mostly with header related lengths
* add `header_value` module defining the `HeaderValue<T>` type along
with its std trait implementations

# TODO

* [x] `write_key` support
* [x] `read_key` support
* [x] perform assertions on header card lengths
* [x] rewrite the change in a backwards compatible way
    - [x] writing a header value is backwards compatible already
- [x] make `read_key` take either a primitive value (backwards
compatible) or `HeaderValue<_>`
* [x] remove public access to `HeaderValue` internals? Or remove methods
  * decifded to keep fields as the type should be simple

fitsio/examples/full_example.rs

@@ -13,6 +13,7 @@
 
 use std::error::Error;
 
+use fitsio::headers::HeaderValue;
 use fitsio::images::{ImageDescription, ImageType};
 use fitsio::tables::{ColumnDataType, ColumnDescription, FitsRow};
 use fitsio::FitsFile;
@@ -46,8 +47,12 @@ fn run() -> Result<(), Box<dyn Error>> {
         /* First we get the primary HDU */
         let hdu = fitsfile.primary_hdu()?;
 
-        /* Now we add the header keys */
-        hdu.write_key(&mut fitsfile, "PROJECT", "My First Astronomy Project")?;
+        /* Now we add the header keys, including a comment */
+        hdu.write_key(
+            &mut fitsfile,
+            "PROJECT",
+            ("My First Astronomy Project", "Project name"),
+        )?;
 
         /* Now the exposure time */
         hdu.write_key(&mut fitsfile, "EXPTIME", 15.2f32)?;
@@ -114,6 +119,27 @@ fn run() -> Result<(), Box<dyn Error>> {
     /* Get the primary HDU and read a section of the image data */
     let phdu = fitsfile.primary_hdu()?;
 
+    /* Read some information from the header. Start with the project */
+    let project_value = phdu.read_key::<HeaderValue<String>>(&mut fitsfile, "PROJECT")?;
+
+    /* `project_value` is a `HeaderValue` type, which has accessors for the value itself, as well
+     * as the comment */
+    let project = project_value.value;
+    assert_eq!(project, "My First Astronomy Project");
+
+    let project_header_comment = project_value.comment;
+    assert_eq!(project_header_comment, Some("Project name".to_string()));
+
+    /* Or of course destructuring is allowed */
+    let HeaderValue {
+        value: _unused_value,
+        comment: _unused_comment,
+    } = phdu.read_key::<HeaderValue<String>>(&mut fitsfile, "PROJECT")?;
+
+    /* Or primitive values can be read as well */
+    let image_id: i64 = phdu.read_key(&mut fitsfile, "IMAGE_ID")?;
+    assert_eq!(image_id, 20180101010005i64);
+
     /* Let's say we have a region around a star that we want to extract. The star is at (25, 25,
      * 1-indexed) and we want to extract a 5x5 box around it. This means we want to read rows 19 to
      * 19, and columns 19 to 29 (0-indexed). The range arguments are exclusive of the upper bound,

fitsio/src/headers/constants.rs

@@ -0,0 +1,4 @@
+// FLEN_VALUE
+pub(super) const MAX_VALUE_LENGTH: usize = 71;
+// FLEN_COMMENT
+pub(super) const MAX_COMMENT_LENGTH: usize = 73;