devices: overhaul documentation

- Standardize package documentation into doc.go
- Link back to the web site in a standardized way
- Update datasheet links for lepton

devices/apa102/doc.go

@@ -11,6 +11,10 @@
 // This driver handles color intensity and temperature correction and uses the
 // full near 8000:1 dynamic range as supported by the device.
 //
+// More details
+//
+// See https://periph.io/device/apa102/ for more details about the device.
+//
 // Datasheet
 //
 // https://cpldcpu.files.wordpress.com/2014/08/apa-102c-super-led-specifications-2014-en.pdf

devices/bmxx80/bmxx80.go

@@ -2,34 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package bmxx80 controls a Bosch BMP180/BME280/BMP280 device over I²C, or SPI
-// for the BMx280.
-//
-// Datasheets
-//
-// The URLs tend to rot, visit https://www.bosch-sensortec.com if they become
-// invalid.
-//
-// BME280:
-// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-12.pdf
-//
-// BMP280:
-// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP280-DS001-19.pdf
-//
-// BMP180:
-// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-12.pdf
-//
-// The font the official datasheet on page 15 is hard to read, a copy with
-// readable text can be found here:
-//
-// https://cdn-shop.adafruit.com/datasheets/BST-BMP180-DS000-09.pdf
-//
-// Notes on the BMP180 datasheet
-//
-// The results of the calculations in the algorithm on page 15 are partly
-// wrong. It looks like the original authors used non-integer calculations and
-// some nubers were rounded. Take the results of the calculations with a grain
-// of salt.
 package bmxx80
 
 import (

devices/bmxx80/doc.go

@@ -0,0 +1,37 @@
+// Copyright 2016 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package bmxx80 controls a Bosch BMP180/BME280/BMP280 device over I²C, or SPI
+// for the BMx280.
+//
+// More details
+//
+// See https://periph.io/device/bmxx80/ for more details about the device.
+//
+// Datasheets
+//
+// The URLs tend to rot, visit https://www.bosch-sensortec.com if they become
+// invalid.
+//
+// BME280:
+// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BME280_DS001-12.pdf
+//
+// BMP280:
+// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP280-DS001-19.pdf
+//
+// BMP180:
+// https://ae-bst.resource.bosch.com/media/_tech/media/datasheets/BST-BMP180-DS000-12.pdf
+//
+// The font the official datasheet on page 15 is hard to read, a copy with
+// readable text can be found here:
+//
+// https://cdn-shop.adafruit.com/datasheets/BST-BMP180-DS000-09.pdf
+//
+// Notes on the BMP180 datasheet
+//
+// The results of the calculations in the algorithm on page 15 are partly
+// wrong. It looks like the original authors used non-integer calculations and
+// some nubers were rounded. Take the results of the calculations with a grain
+// of salt.
+package bmxx80

devices/ds18b20/doc.go

@@ -0,0 +1,26 @@
+// Copyright 2016 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820
+// 1-wire temperature sensors.
+//
+// Note that both DS18B20 and MAX31820 use family code 0x28.
+//
+// Both powered sensors and parasitically powered sensors are supported
+// as long as the bus driver can provide sufficient power using an active
+// pull-up.
+//
+// The DS18B20 alarm functionality and reading/writing the 2 alarm bytes in
+// the EEPROM are not supported. The DS18S20 is also not supported.
+//
+// More details
+//
+// See https://periph.io/device/ds18b20/ for more details about the device.
+//
+// Datasheets
+//
+// https://datasheets.maximintegrated.com/en/ds/DS18B20-PAR.pdf
+//
+// http://datasheets.maximintegrated.com/en/ds/MAX31820.pdf
+package ds18b20

devices/ds18b20/ds18b20.go

@@ -2,23 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package ds18b20 interfaces to Dallas Semi / Maxim DS18B20 and MAX31820
-// 1-wire temperature sensors.
-//
-// Note that both DS18B20 and MAX31820 use family code 0x28.
-//
-// Both powered sensors and parasitically powered sensors are supported
-// as long as the bus driver can provide sufficient power using an active
-// pull-up.
-//
-// The DS18B20 alarm functionality and reading/writing the 2 alarm bytes in
-// the EEPROM are not supported. The DS18S20 is also not supported.
-//
-// Datasheets
-//
-// https://datasheets.maximintegrated.com/en/ds/DS18B20-PAR.pdf
-//
-// http://datasheets.maximintegrated.com/en/ds/MAX31820.pdf
 package ds18b20
 
 import (

devices/ds248x/doc.go

@@ -0,0 +1,17 @@
+// Copyright 2016 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip
+// over I²C.
+//
+// More details
+//
+// See https://periph.io/device/ds248x/ for more details about the device.
+//
+// Datasheets
+//
+// https://www.maximintegrated.com/en/products/digital/one-wire/DS2483.html
+//
+// https://www.maximintegrated.com/en/products/interface/controllers-expanders/DS2482-100.html
+package ds248x

devices/ds248x/ds248x.go

@@ -2,13 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package ds248x controls a Maxim DS2483 or DS2482-100 1-wire interface chip over I²C.
-//
-// Datasheets
-//
-// https://www.maximintegrated.com/en/products/digital/one-wire/DS2483.html
-//
-// https://www.maximintegrated.com/en/products/interface/controllers-expanders/DS2482-100.html
 package ds248x
 
 import (

devices/lepton/cci/cci.go

@@ -5,17 +5,6 @@
 // "stringer" can be installed with "go get golang.org/x/tools/cmd/stringer"
 //go:generate stringer -output=strings_gen.go -type=CameraStatus,command,FFCShutterMode,FFCState,ShutterPos,ShutterTempLockoutState
 
-// Package cci declares the Camera Command Interface to interact with a FLIR
-// Lepton over I²C.
-//
-// This protocol controls and queries the camera but is not used to read the
-// images.
-//
-// Datasheet
-//
-// http://www.flir.com/uploadedFiles/OEM/Products/LWIR-Cameras/Lepton/FLIR-Lepton-Software-Interface-Description-Document.pdf
-//
-// Found via http://www.flir.com/cores/display/?id=51878
 package cci
 
 import (

devices/lepton/cci/doc.go

@@ -0,0 +1,14 @@
+// Copyright 2017 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package cci declares the Camera Command Interface to interact with a FLIR
+// Lepton over I²C.
+//
+// This protocol controls and queries the camera but is not used to read the
+// images.
+//
+// Datasheet
+//
+// https://www.flir.com/globalassets/imported-assets/document/flir-lepton-software-interface-description-document.pdf
+package cci

devices/lepton/doc.go

@@ -0,0 +1,14 @@
+// Copyright 2017 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package lepton drives a FLIR Lepton Infra Red (IR) camera.
+//
+// More details
+//
+// See https://periph.io/device/lepton/ for more details about the device.
+//
+// Datasheet
+//
+// https://www.flir.com/globalassets/imported-assets/document/lepton-engineering-datasheet---with-radiometry.pdf
+package lepton

devices/lepton/lepton.go

@@ -2,18 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package lepton drivers a FLIR Lepton.
-//
-// References
-//
-// Official FLIR reference:
-//   http://www.flir.com/cvs/cores/view/?id=51878
-//
-// Product page:
-//   http://www.flir.com/cores/content/?id=66257
-//
-// Datasheet:
-//   http://www.flir.com/uploadedFiles/OEM/Products/LWIR-Cameras/Lepton/Lepton%20Engineering%20Datasheet%20-%20with%20Radiometry.pdf
 package lepton
 
 import (

devices/lirc/doc.go

@@ -5,50 +5,8 @@
 // Package lirc implements InfraRed receiver support through native linux app
 // lirc.
 //
-// Configuration
+// More details
 //
-// lircd MUST be configured via TWO files: /etc/lirc/hardware.conf and
+// See https://periph.io/device/ir/ for more details about the driver, as it
-// /etc/lirc/lircd.conf.
+// requires host configuration.
-//
-// See http://www.lirc.org/ for more details about daemon configuration.
-//
-// /etc/lirc/hardware.conf
-//
-// This file contains the interaction between the lircd process and the kernel
-// driver, if any. This is the link between the physical signal and decoding
-// pulses.
-//
-// /etc/lirc/lircd.conf
-//
-// This file contains all the known IR codes for the remotes you plan to use
-// and convert into key codes. This means you need to "train" lircd with the
-// remotes you plan to use.
-//
-// Keys are listed at
-// http://www.lirc.org/api-docs/html/input__map_8inc_source.html
-//
-// Debugging
-//
-// Here's a quick recipe to train a remote:
-//
-//     # Detect your remote
-//     irrecord -a -d /var/run/lirc/lircd ~/lircd.conf
-//     # Grep for key names you found to find the remote in the remotes library
-//     grep -R '<hex value>' /usr/share/lirc/remotes/
-//     # Listen and send command to the server
-//     nc -U /var/run/lirc/lircd
-//     # List all valid key names
-//     irrecord -l
-//     grep -hoER '(BTN|KEY)_\w+' /usr/share/lirc/remotes | sort | uniq | less
-//
-// Raspbian
-//
-// Please see documentation of package periph/host/rpi for details on how to set
-// it up.
-//
-// Hardware
-//
-// A good device is the VS1838. Then you need device driver for hardware
-// accelerated signal decoding, that lircd will then leverage to decode the
-// keypresses.
 package lirc

devices/ssd1306/doc.go

@@ -0,0 +1,35 @@
+// Copyright 2016 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306
+// controller.
+//
+// The driver does differential updates: it only sends modified pixels for the
+// smallest rectangle, to economize bus bandwidth. This is especially important
+// when using I²C as the bus default speed (often 100kHz) is slow enough to
+// saturate the bus at less than 10 frames per second.
+//
+// The SSD1306 is a write-only device. It can be driven on either I²C or SPI
+// with 4 wires. Changing between protocol is likely done through resistor
+// soldering, for boards that support both.
+//
+// Some boards expose a RES / Reset pin. If present, it must be normally be
+// High. When set to Low (Ground), it enables the reset circuitry. It can be
+// used externally to this driver, if used, the driver must be reinstantiated.
+//
+// More details
+//
+// See https://periph.io/device/ssd1306/ for more details about the device.
+//
+// Datasheets
+//
+// Product page:
+// http://www.solomon-systech.com/en/product/display-ic/oled-driver-controller/ssd1306/
+//
+// https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf
+//
+// "DM-OLED096-624": https://drive.google.com/file/d/0B5lkVYnewKTGaEVENlYwbDkxSGM/view
+//
+// "ssd1306": https://drive.google.com/file/d/0B5lkVYnewKTGYzhyWWp0clBMR1E/view
+package ssd1306

devices/ssd1306/ssd1306.go

@@ -2,32 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package ssd1306 controls a 128x64 monochrome OLED display via a SSD1306
-// controller.
-//
-// The driver does differential updates: it only sends modified pixels for the
-// smallest rectangle, to economize bus bandwidth. This is especially important
-// when using I²C as the bus default speed (often 100kHz) is slow enough to
-// saturate the bus at less than 10 frames per second.
-//
-// The SSD1306 is a write-only device. It can be driven on either I²C or SPI
-// with 4 wires. Changing between protocol is likely done through resistor
-// soldering, for boards that support both.
-//
-// Some boards expose a RES / Reset pin. If present, it must be normally be
-// High. When set to Low (Ground), it enables the reset circuitry. It can be
-// used externally to this driver, if used, the driver must be reinstantiated.
-//
-// Datasheets
-//
-// Product page:
-// http://www.solomon-systech.com/en/product/display-ic/oled-driver-controller/ssd1306/
-//
-// https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf
-//
-// "DM-OLED096-624": https://drive.google.com/file/d/0B5lkVYnewKTGaEVENlYwbDkxSGM/view
-//
-// "ssd1306": https://drive.google.com/file/d/0B5lkVYnewKTGYzhyWWp0clBMR1E/view
 package ssd1306
 
 // Some have SPI enabled;

devices/tm1637/doc.go

@@ -0,0 +1,14 @@
+// Copyright 2016 The Periph Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package tm1637 controls a TM1637 device over GPIO pins.
+//
+// More details
+//
+// See https://periph.io/device/tm1637/ for more details about the device.
+//
+// Datasheet
+//
+// http://olimex.cl/website_MCI/static/documents/Datasheet_TM1637.pdf
+package tm1637

devices/tm1637/tm1637.go

@@ -2,11 +2,6 @@
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
-// Package tm1637 controls a TM1637 device over GPIO pins.
-//
-// Datasheet
-//
-// http://olimex.cl/website_MCI/static/documents/Datasheet_TM1637.pdf
 package tm1637
 
 import (