Extend the documentation of sensors_init() and

sensors_get_adapter_name(). Paul Crawford asked questions about these
as he found the original documentation unclear. I'm including my
answers to his questions here, reformatted, so that other developers
can benefit from them too.

CHANGES

@@ -2,6 +2,7 @@ lm-sensors CHANGES file
 -----------------------
 
 SVN HEAD
+  libsensors: Improve documentation of two functions
   init: Fix EnvironmentFile in service files
   sensors-detect: Report built-in drivers as such
                   Use modules.builtin instead of /sys/module

lib/init.c

@@ -175,6 +175,8 @@ static int add_config_from_dir(const char *dir)
 	return res;
 }
 
+/* Ideally, initialization and configuraton file loading should be exposed
+   separately, to make it possible to load several configuration files. */
 int sensors_init(FILE *input)
 {
 	int res;

lib/libsensors.3

@@ -1,5 +1,5 @@
 .\" Copyright (C) 1998, 1999  Adrian Baugh <adrian.baugh@keble.ox.ac.uk>
-.\" Copyright (C) 2007, 2009  Jean Delvare <khali@linux-fr.org>
+.\" Copyright (C) 2007, 2009, 2013  Jean Delvare <khali@linux-fr.org>
 .\" based on sensors.h, part of libsensors by Frodo Looijaard
 .\" libsensors is distributed under the LGPL
 .\"
@@ -25,7 +25,7 @@
 .\"
 .\" References consulted:
 .\"     libsensors source code
-.TH libsensors 3  "February 2009" "lm-sensors 3" "Linux Programmer's Manual"
+.TH libsensors 3  "September 2013" "lm-sensors 3" "Linux Programmer's Manual"
 
 .SH NAME
 libsensors \- publicly accessible functions provided by the sensors library
@@ -88,8 +88,12 @@ libsensors \- publicly accessible functions provided by the sensors library
 .B sensors_init()
 loads the configuration file and the detected chips list. If this returns a
 value unequal to zero, you are in trouble; you can not assume anything will
-be initialized properly. If you want to reload the configuration file, call
-sensors_cleanup() below before calling sensors_init() again.
+be initialized properly. If you want to reload the configuration file, or
+load a different configuration file, call sensors_cleanup() below before
+calling sensors_init() again. This means you can't load multiple configuration
+files at once by calling sensors_init() multiple times.
+
+The configuration file format is described in sensors.conf(5).
 
 If FILE is NULL, the default configuration files are used (see the FILES
 section below). Most applications will want to do that.
@@ -117,9 +121,20 @@ not contain wildcard values! Return the number of characters printed on
 success (same as snprintf), <0 on error.
 
 .B sensors_get_adapter_name()
-returns the adapter name of a bus number, as used within the
+returns the adapter name of a bus type, number pair, as used within the
 sensors_chip_name structure. If it could not be found, it returns NULL.
 
+Adapters describe how a monitoring chip is hooked up to the system.
+This is particularly relevant for I2C/SMBus sensor chips (bus type "i2c"),
+which must be accessed over an I2C/SMBus controller. Each such controller
+has a different number, assigned by the system at initialization time,
+so that they can be referenced individually.
+
+Super\-I/O or CPU\-embedded sensors, on the other hand, can be accessed
+directly and technically don't use any adapter. They have only a bus type
+but no bus number, and sensors_get_adapter_name() will return a generic
+adapter name for them.
+
 .B sensors_get_detected_chips()
 returns all detected chips that match a given chip name,
 one by one. If no chip name is provided, all detected chips are returned.
@@ -258,6 +273,6 @@ ignored.
 sensors.conf(5)
 
 .SH AUTHOR
-Frodo Looijaard and the lm_sensors group
+Frodo Looijaard, Jean Delvare and others
 http://www.lm-sensors.org/