(#5394) Document each Facter fact.

Document all the builtin Facter facts in puppetdoc/rdoc format.

This is laying the ground work for using a tool like puppet doc, or puppet
describe but for facter, so you can see what a fact is for and how it
resolves this. This is the "leg work" of documenting the actual facts, and
the syntax of them may change in future.

44 files changed, 555 insertions, 10 deletions

diff --git a/lib/facter/Cfkey.rb b/lib/facter/Cfkey.rb
index a4e0c11..8353392 100644
--- a/lib/facter/Cfkey.rb
+++ b/lib/facter/Cfkey.rb
@@ -1,3 +1,14 @@
+# Fact: Cfkey
+#
+# Purpose: Return the public key(s) for CFengine.
+#
+# Resolution:
+#   Tries each file of standard localhost.pub & cfkey.pub locations,
+#   checks if they appear to be a public key, and then join them all together.
+#
+# Caveats:
+#
+
 ## Cfkey.rb
 ## Facts related to cfengine
 ##
diff --git a/lib/facter/architecture.rb b/lib/facter/architecture.rb
index e4aaeba..cd606a2 100644
--- a/lib/facter/architecture.rb
+++ b/lib/facter/architecture.rb
@@ -1,3 +1,16 @@
+# Fact: architecture
+#
+# Purpose:
+#   Return the CPU hardware architecture.
+# 
+# Resolution:
+#   On OpenBSD, Linux and Debian's kfreebsd, use the hardwaremodel fact.
+#   Gentoo and Debian call "x86_86" "amd64".
+#   Gentoo also calls "i386" "x86".
+#
+# Caveats:
+#
+
 Facter.add(:architecture) do
     confine :kernel => [:linux, :"gnu/kfreebsd"]
     setcode do
diff --git a/lib/facter/domain.rb b/lib/facter/domain.rb
index 29bb204..2a79754 100644
--- a/lib/facter/domain.rb
+++ b/lib/facter/domain.rb
@@ -1,3 +1,23 @@
+# Fact: domain
+#
+# Purpose:
+#   Return the host's primary DNS domain name.
+# 
+# Resolution:
+#   On UNIX (excluding Darwin), first try and use the hostname fact,
+#   which uses the hostname system command, and then parse the output
+#   of that.
+#   Failing that it tries the dnsdomainname system command.
+#   Failing that it uses /etc/resolv.conf and takes the domain from that, or as
+#   a final resort, the search from that.
+#   Otherwise returns nil.
+#
+#   On Windows uses the win32ole gem and winmgmts to get the DNSDomain value
+#   from the Win32 networking stack.
+#
+# Caveats:
+#
+
 Facter.add(:domain) do
     setcode do
         # Get the domain from various sources; the order of these
diff --git a/lib/facter/facterversion.rb b/lib/facter/facterversion.rb
index 0b1cfda..574da99 100644
--- a/lib/facter/facterversion.rb
+++ b/lib/facter/facterversion.rb
@@ -1,3 +1,12 @@
+# Fact: facterversion
+#
+# Purpose: returns the version of the facter module.
+#
+# Resolution: Uses the version constant.
+#
+# Caveats:
+#
+
 Facter.add(:facterversion) do
     setcode { Facter::FACTERVERSION.to_s }
 end
diff --git a/lib/facter/fqdn.rb b/lib/facter/fqdn.rb
index 5ebc5f5..090ca63 100644
--- a/lib/facter/fqdn.rb
+++ b/lib/facter/fqdn.rb
@@ -1,3 +1,14 @@
+# Fact: fqdn
+#
+# Purpose: Returns the fully qualified domain name of the host.
+#
+# Resolution: Simply joins the hostname fact with the domain name fact.
+#
+# Caveats: No attempt is made to check that the two facts are accurate or that
+# the two facts go together. At no point is there any DNS resolution made
+# either.
+#
+
 Facter.add(:fqdn) do
     setcode do
         host = Facter.value(:hostname)
diff --git a/lib/facter/hardwareisa.rb b/lib/facter/hardwareisa.rb
index 23f7d08..9d0830e 100644
--- a/lib/facter/hardwareisa.rb
+++ b/lib/facter/hardwareisa.rb
@@ -1,3 +1,15 @@
+# Fact: hardwareisa
+#
+# Purpose:
+#   Returns hardware processor type.
+#
+# Resolution:
+#   On Solaris, Linux and the BSDs simply uses the output of "uname -p"
+#
+# Caveats:
+#   Some linuxes return unknown to uname -p with relative ease.
+#
+
 Facter.add(:hardwareisa) do
     setcode 'uname -p', '/bin/sh'
     confine :operatingsystem => %w{Solaris Linux Fedora RedHat CentOS SuSE SLES Debian Ubuntu Gentoo FreeBSD OpenBSD NetBSD OEL OVS GNU/kFreeBSD}
diff --git a/lib/facter/hardwaremodel.rb b/lib/facter/hardwaremodel.rb
index 6201bdd..8f52fef 100644
--- a/lib/facter/hardwaremodel.rb
+++ b/lib/facter/hardwaremodel.rb
@@ -1,3 +1,16 @@
+# Fact: hardwaremodel
+#
+# Purpose:
+#   Returns the hardware model of the system.
+#
+# Resolution:
+#   Uses purely "uname -m" on all platforms other than AIX and Windows.
+#   On AIX uses the parsed "modelname" output of "lsattr -El sys0 -a modelname".
+#   On Windows uses the 'host_cpu' pulled out of Ruby's config.
+#
+# Caveats:
+#
+
 Facter.add(:hardwaremodel) do
     setcode 'uname -m'
 end
diff --git a/lib/facter/hostname.rb b/lib/facter/hostname.rb
index 188efa4..0dcd01c 100644
--- a/lib/facter/hostname.rb
+++ b/lib/facter/hostname.rb
@@ -1,3 +1,16 @@
+# Fact: hostname
+#
+# Purpose: Return the system's short hostname.
+#
+# Resolution:
+#   On all system bar Darwin, parses the output of the "hostname" system command
+#   to everything before the first period.
+#   On Darwin, uses the system configuration util to get the LocalHostName
+#   variable.
+#
+# Caveats:
+#
+
 Facter.add(:hostname, :ldapname => "cn") do
     setcode do
         hostname = nil
diff --git a/lib/facter/id.rb b/lib/facter/id.rb
index 1c42284..cc0a0a6 100644
--- a/lib/facter/id.rb
+++ b/lib/facter/id.rb
@@ -1,3 +1,16 @@
+# Fact: id
+#
+# Purpose: Internal fact used to specity the program to return the currently
+# running user id.
+#
+# Resolution:
+#   On all Unixes bar Solaris, just returns "whoami".
+#   On Solaris, parses the output of the "id" command to grab the username, as
+#   Solaris doesn't have the whoami command.
+#
+# Caveats:
+#
+
 Facter.add(:id) do
     setcode "whoami"
 end
diff --git a/lib/facter/interfaces.rb b/lib/facter/interfaces.rb
index 4fbaef1..04b1c19 100644
--- a/lib/facter/interfaces.rb
+++ b/lib/facter/interfaces.rb
@@ -1,3 +1,12 @@
+# Fact: interfaces
+#
+# Purpose:
+#
+# Resolution:
+#
+# Caveats:
+#
+
 # interfaces.rb
 # Try to get additional Facts about the machine's network interfaces
 #
diff --git a/lib/facter/ipaddress.rb b/lib/facter/ipaddress.rb
index d563408..5260504 100644
--- a/lib/facter/ipaddress.rb
+++ b/lib/facter/ipaddress.rb
@@ -1,3 +1,27 @@
+# Fact: ipaddress
+#
+# Purpose: Return the main IP address for a host.
+#
+# Resolution:
+#   On the Unixes does an ifconfig, and returns the first non 127.0.0.0/8
+#   subnetted IP it finds.
+#   On Windows, it attempts to use the socket library and resolve the machine's
+#   hostname via DNS.
+#
+#   On LDAP based hosts it tries to use either the win32/resolv library to
+#   resolve the hostname to an IP address, or on Unix, it uses the resolv
+#   library.
+#
+#   As a fall back for undefined systems, it tries to run the "host" command to
+#   resolve the machine's hostname using the system DNS.
+#
+# Caveats:
+#   DNS resolution relies on working DNS infrastructure and resolvers on the
+#   host system.
+#   The ifconfig parsing purely takes the first IP address it finds without any
+#   checking this is a useful IP address.
+#
+
 Facter.add(:ipaddress) do
     confine :kernel => :linux
     setcode do
diff --git a/lib/facter/ipaddress6.rb b/lib/facter/ipaddress6.rb
index 547d636..b494b9d 100644
--- a/lib/facter/ipaddress6.rb
+++ b/lib/facter/ipaddress6.rb
@@ -1,17 +1,26 @@
+# Fact: ipaddress6
+#
+# Purpose: Returns the "main" IPv6 IP address of a system.
+#
+# Resolution:
+#  OS dependant code that parses the output of various networking
+#  tools and currently not very intelligent. Returns the first
+#  non-loopback and non-linklocal address found in the ouput unless
+#  a default route can be mapped to a routeable interface. Guessing
+#  an interface is currently only possible with BSD type systems
+#  to many assumptions have to be made on other platforms to make
+#  this work with the current code. Most code ported or modeled
+#  after the ipaddress fact for the sake of similar functionality
+#  and familiar mechanics.
+#
+# Caveats:
+#
+
 # Cody Herriges <c.a.herriges@gmail.com>
 #
 # Used the ipaddress fact that is already part of
 # Facter as a template.
 
-# OS dependant code that parses the output of various networking
-# tools and currently not very intelligent. Returns the first
-# non-loopback and non-linklocal address found in the ouput unless
-# a default route can be mapped to a routeable interface. Guessing
-# an interface is currently only possible with BSD type systems
-# to many assumptions have to be made on other platforms to make
-# this work with the current code. Most code ported or modeled
-# after the ipaddress fact for the sake of similar functionality
-# and familiar mechanics.
 Facter.add(:ipaddress6) do
   confine :kernel => :linux
   setcode do
diff --git a/lib/facter/iphostnumber.rb b/lib/facter/iphostnumber.rb
index bc38432..cddaadd 100644
--- a/lib/facter/iphostnumber.rb
+++ b/lib/facter/iphostnumber.rb
@@ -1,3 +1,14 @@
+# Fact: iphostnumber
+#
+# Purpose: On selected versions of Darwin, returns the host's IP address.
+#
+# Resolution:
+#   Uses either the scutil program to get the localhost name, or parses output
+#   of ifconfig for a MAC address.
+#
+# Caveats:
+#
+
 Facter.add(:iphostnumber) do
     confine :kernel => :darwin, :kernelrelease => "R6"
     setcode do
diff --git a/lib/facter/kernel.rb b/lib/facter/kernel.rb
index 66f21ce..f457e01 100644
--- a/lib/facter/kernel.rb
+++ b/lib/facter/kernel.rb
@@ -1,3 +1,14 @@
+# Fact: kernel
+#
+# Purpose: Returns the operating system's name.
+#
+# Resolution:
+#   Uses Ruby's rbconfig to find host_os, if that is a Windows derivative, the
+#   returns 'windows', otherwise returns "uname -s" verbatim.
+#
+# Caveats:
+#
+
 Facter.add(:kernel) do
     setcode do
         require 'rbconfig'
diff --git a/lib/facter/kernelmajversion.rb b/lib/facter/kernelmajversion.rb
index 32fd7aa..84f71d4 100644
--- a/lib/facter/kernelmajversion.rb
+++ b/lib/facter/kernelmajversion.rb
@@ -1,3 +1,13 @@
+# Fact: kernelmajversion
+#
+# Purpose: Return the operating system's release number's major value.
+#
+# Resolution:
+#   Takes the first 2 elements of the kernel version as delimited by periods.
+#
+# Caveats:
+#
+
 Facter.add("kernelmajversion") do
     setcode do
         Facter.value(:kernelversion).split('.')[0..1].join('.')
diff --git a/lib/facter/kernelrelease.rb b/lib/facter/kernelrelease.rb
index 2f6ae45..a6f9c2c 100644
--- a/lib/facter/kernelrelease.rb
+++ b/lib/facter/kernelrelease.rb
@@ -1,3 +1,16 @@
+# Fact: kernelrelease
+#
+# Purpose: Return the operating system's release number.
+#
+# Resolution:
+#   On AIX returns the output from the "oslevel -s" system command.
+#   On Windows based systems, uses the win32ole gem to query Windows Management
+#   for the 'Win32_OperatingSystem' value.
+#   Otherwise uses the output of "uname -r" system command.
+#
+# Caveats:
+#
+
 Facter.add(:kernelrelease) do
     setcode 'uname -r'
 end
diff --git a/lib/facter/kernelversion.rb b/lib/facter/kernelversion.rb
index cac6c14..7e0d95c 100644
--- a/lib/facter/kernelversion.rb
+++ b/lib/facter/kernelversion.rb
@@ -1,3 +1,15 @@
+# Fact: kernelversion
+#
+# Purpose: Return the operating system's kernel version.
+#
+# Resolution:
+#   On Solaris and SunOS based machines, returns the output of "uname -v".
+#   Otherwise returns the 'kernerlversion' fact up to the first '-'. This may be
+#   the entire 'kernelversion' fact in many cases.
+#
+# Caveats:
+#
+
 Facter.add("kernelversion") do
     setcode do
         Facter['kernelrelease'].value.split('-')[0]
diff --git a/lib/facter/lsb.rb b/lib/facter/lsb.rb
index bf4b9db..107419a 100644
--- a/lib/facter/lsb.rb
+++ b/lib/facter/lsb.rb
@@ -1,3 +1,16 @@
+# Fact: lsb
+#
+# Purpose: Return Linux Standard Base information for the host.
+#
+# Resolution:
+#   Uses the lsb_release system command and parses the output with a series of
+#   regular expressions.
+#
+# Caveats:
+#   Only works on Linux (and the kfreebsd derivative) systems.
+#   Requires the lsb_release program, which may not be installed by default.
+#   Also is as only as accurate as that program outputs.
+
 ## lsb.rb
 ## Facts related to Linux Standard Base (LSB)
 ##
diff --git a/lib/facter/lsbmajdistrelease.rb b/lib/facter/lsbmajdistrelease.rb
index 34a2f1e..3659541 100644
--- a/lib/facter/lsbmajdistrelease.rb
+++ b/lib/facter/lsbmajdistrelease.rb
@@ -1,3 +1,15 @@
+# Fact: lsbmajdistrelease
+#
+# Purpose: Returns the major version of the operation system version as gleaned
+# from the lsbdistrelease fact.
+#
+# Resolution:
+#   Parses the lsbdistrelease fact for numbers followed by a period and
+#   returns those, or just the lsbdistrelease fact if none were found.
+#
+# Caveats:
+#
+
 # lsbmajdistrelease.rb
 #
 require 'facter'
diff --git a/lib/facter/macaddress.rb b/lib/facter/macaddress.rb
index bf23ef6..54c3c84 100644
--- a/lib/facter/macaddress.rb
+++ b/lib/facter/macaddress.rb
@@ -1,3 +1,12 @@
+# Fact: macaddress
+#
+# Purpose: 
+#
+# Resolution:
+#
+# Caveats:
+#
+
 require 'facter/util/macaddress'
 
 Facter.add(:macaddress) do
diff --git a/lib/facter/macosx.rb b/lib/facter/macosx.rb
index 3841c50..f5289df 100644
--- a/lib/facter/macosx.rb
+++ b/lib/facter/macosx.rb
@@ -1,3 +1,16 @@
+# Fact: macosx
+#
+# Purpose:
+#   Returns a number of Mac specific facts, from system profiler and
+#   sw_vers.
+#
+# Resolution:
+#   Uses util/macosx.rb to do the fact reconnaissance, then outputs them
+#   preceded by 'sp_'
+#
+# Caveats:
+#
+
 #
 # macosx.rb
 # Additional Facts coming from Mac OS X system_profiler command
diff --git a/lib/facter/manufacturer.rb b/lib/facter/manufacturer.rb
index 4f2df98..26aef5f 100644
--- a/lib/facter/manufacturer.rb
+++ b/lib/facter/manufacturer.rb
@@ -1,3 +1,16 @@
+# Fact: manufacturer
+#
+# Purpose: Return the hardware manufacturer information about the hardware.
+#
+# Resolution:
+#   On OpenBSD, queries sysctl values, via a util class.
+#   On SunOS Sparc, uses prtdiag via a util class.
+#   On Windows, queries the system via a util class.
+#   Uses the 'util/manufacturer.rb' for fallback parsing.
+#
+# Caveats:
+#
+
 # manufacturer.rb
 # Facts related to hardware manufacturer
 #
diff --git a/lib/facter/memory.rb b/lib/facter/memory.rb
index 0aa5e88..992f2ad 100644
--- a/lib/facter/memory.rb
+++ b/lib/facter/memory.rb
@@ -1,3 +1,20 @@
+# Fact: memory
+#
+# Purpose: Return information about memory and swap usage.
+#
+# Resolution:
+#   On Linuxes, uses Facter::Memory.meminfo_number from
+#   'facter/util/memory.rb'
+#   On AIX, parses "swap -l" for swap values only.
+#   On OpenBSD, it parses "swapctl -l" for swap values, vmstat via a module for
+#   free memory, and "sysctl hw.physmem" for maximum memory.
+#   On Solaris, use "swap -l" for swap values, and parsing prtconf for maximum
+#   memory, and again, the vmstat module for free memory.
+#
+# Caveats:
+#   Some BSD platforms aren't covered at all. AIX is missing memory values.
+#
+
 # memory.rb
 # Additional Facts for memory/swap usage
 #
diff --git a/lib/facter/netmask.rb b/lib/facter/netmask.rb
index d6d125e..fbb84f5 100644
--- a/lib/facter/netmask.rb
+++ b/lib/facter/netmask.rb
@@ -1,3 +1,12 @@
+# Fact: netmask
+#
+# Purpose: Returns the netmask for the main interfaces.
+#
+# Resolution: Uses the facter/util/netmask library routines.
+#
+# Caveats:
+#
+
 # netmask.rb
 # Find the netmask of the primary ipaddress
 # Copyright (C) 2007 David Schmitt <david@schmitt.edv-bus.at>
diff --git a/lib/facter/network.rb b/lib/facter/network.rb
index df53ce4..d4faaac 100644
--- a/lib/facter/network.rb
+++ b/lib/facter/network.rb
@@ -1,3 +1,15 @@
+# Fact: network
+#
+# Purpose:
+# Get IP, network and netmask information for available network
+# interfacs.
+#
+# Resolution:
+#  Uses 'facter/util/ip' to enumerate interfaces and return their information.
+#
+# Caveats:
+#
+
 require 'facter/util/ip'
 
 Facter::Util::IP.get_interfaces.each do |interface|
diff --git a/lib/facter/operatingsystem.rb b/lib/facter/operatingsystem.rb
index 25eeb00..a90c283 100644
--- a/lib/facter/operatingsystem.rb
+++ b/lib/facter/operatingsystem.rb
@@ -1,3 +1,16 @@
+# Fact: operatingsystem
+#
+# Purpose: Return the name of the operating system.
+#
+# Resolution:
+#   If the kernel is a Linux kernel, check for the existence of a selection of
+#   files in /etc/ to find the specific flavour.
+#   On SunOS based kernels, return Solaris.
+#   On systems other than Linux, use the kernel value.
+#
+# Caveats:
+#
+
 require 'facter/lsb'
 
 Facter.add(:operatingsystem) do
diff --git a/lib/facter/operatingsystemrelease.rb b/lib/facter/operatingsystemrelease.rb
index da1b76a..347fe7f 100644
--- a/lib/facter/operatingsystemrelease.rb
+++ b/lib/facter/operatingsystemrelease.rb
@@ -1,3 +1,20 @@
+# Fact: operatingsystemrelease
+#
+# Purpose: Returns the release of the operating system.
+#
+# Resolution:
+#   On RedHat derivatives, returns their '/etc/<variant>-release' file.
+#   On Debian, returns '/etc/debian_version'.
+#   On Ubuntu, parses '/etc/issue' for the release version.
+#   On Suse, derivatives, parses '/etc/SuSE-release' for a selection of version
+#   information.
+#   On Slackware, parses '/etc/slackware-version'.
+#   
+#   On all remaining systems, returns the 'kernelrelease' value.
+#
+# Caveats:
+#
+
 Facter.add(:operatingsystemrelease) do
     confine :operatingsystem => %w{CentOS Fedora oel ovs RedHat MeeGo}
     setcode do
diff --git a/lib/facter/path.rb b/lib/facter/path.rb
index 03907c0..71df6cd 100644
--- a/lib/facter/path.rb
+++ b/lib/facter/path.rb
@@ -1,3 +1,12 @@
+# Fact: path
+#
+# Purpose: Returns the $PATH variable.
+#
+# Resolution: Gets $PATH from the environment.
+#
+# Caveats:
+#
+
 Facter.add(:path) do
     setcode do
         ENV['PATH']
diff --git a/lib/facter/physicalprocessorcount.rb b/lib/facter/physicalprocessorcount.rb
index 8fe643e..9c59614 100644
--- a/lib/facter/physicalprocessorcount.rb
+++ b/lib/facter/physicalprocessorcount.rb
@@ -1,3 +1,14 @@
+# Fact: physicalprocessorcount
+#
+# Purpose: Return the number of physical processors.
+#
+# Resolution:
+#   On linux, parses the output of '/proc/cpuinfo' for the number of unique
+#   lines with "physical id" in them.
+#
+# Caveats:
+#
+
 Facter.add("physicalprocessorcount") do
     confine :kernel => :linux
 
diff --git a/lib/facter/processor.rb b/lib/facter/processor.rb
index c71bad4..ec196b2 100644
--- a/lib/facter/processor.rb
+++ b/lib/facter/processor.rb
@@ -1,5 +1,18 @@
+# Fact: processor
+#
+# Purpose:
+#   Additional Facts about the machine's CPUs.
+#
+# Resolution:
+#   On Linux and kFreeBSD, parse '/proc/cpuinfo' for each processor.
+#   On AIX, parse the output of 'lsdev' for it's processor section.
+#   On OpenBSD, use 'uname -p' and the sysctl variable for 'hw.ncpu' for CPU
+#   count.
+#
+# Caveats:
+#
+
 # processor.rb
-# Additional Facts about the machine's CPUs
 #
 # Copyright (C) 2006 Mooter Media Ltd
 # Author: Matthew Palmer <matt@solutionsfirst.com.au>
diff --git a/lib/facter/ps.rb b/lib/facter/ps.rb
index e7bcdae..ef803fb 100644
--- a/lib/facter/ps.rb
+++ b/lib/facter/ps.rb
@@ -1,3 +1,15 @@
+# Fact: ps
+#
+# Purpose: Internal fact for what to use to list all processes. Used by
+# Service{} type in Puppet.
+#
+# Resolution:
+#   Assumes "ps -ef" for all operating systems other than BSD derivatives, where
+#   it uses "ps auxwww"
+#
+# Caveats:
+#
+
 Facter.add(:ps) do
     setcode do 'ps -ef' end
 end
diff --git a/lib/facter/puppetversion.rb b/lib/facter/puppetversion.rb
index d2eb1f3..01422f0 100644
--- a/lib/facter/puppetversion.rb
+++ b/lib/facter/puppetversion.rb
@@ -1,3 +1,13 @@
+# Fact: puppetversion
+#
+# Purpose: Return the version of puppet installed.
+#
+# Resolution:
+#   Requres puppet via Ruby and returns it's version constant.
+#
+# Caveats:
+#
+
 Facter.add(:puppetversion) do
     setcode do
         begin
diff --git a/lib/facter/rubysitedir.rb b/lib/facter/rubysitedir.rb
index c205322..9973329 100644
--- a/lib/facter/rubysitedir.rb
+++ b/lib/facter/rubysitedir.rb
@@ -1,3 +1,13 @@
+# Fact: rubysitedir
+#
+# Purpose: Returns Ruby's site library directory.
+#
+# Resolution: Works out the version to major/minor (1.8, 1.9, etc), then joins
+# that with all the $: library paths.
+#
+# Caveats:
+#
+
 Facter.add :rubysitedir do
     setcode do
         version = RUBY_VERSION.to_s.sub(/\.\d+$/, '')
diff --git a/lib/facter/rubyversion.rb b/lib/facter/rubyversion.rb
index 48f5cc8..e578400 100644
--- a/lib/facter/rubyversion.rb
+++ b/lib/facter/rubyversion.rb
@@ -1,3 +1,12 @@
+# Fact: rubyversion
+#
+# Purpose: Returns the version of Ruby facter is running under.
+#
+# Resolution: Returns RUBY_VERSION.
+#
+# Caveats:
+#
+
 Facter.add(:rubyversion) do
     setcode { RUBY_VERSION.to_s }
 end
diff --git a/lib/facter/selinux.rb b/lib/facter/selinux.rb
index 9fab427..1555da0 100644
--- a/lib/facter/selinux.rb
+++ b/lib/facter/selinux.rb
@@ -1,3 +1,12 @@
+# Fact: selinux
+#
+# Purpose:
+#
+# Resolution:
+#
+# Caveats:
+#
+
 # Fact for SElinux
 # Written by immerda admin team (admin(at)immerda.ch)
 
diff --git a/lib/facter/ssh.rb b/lib/facter/ssh.rb
index 318e9d4..beb5692 100644
--- a/lib/facter/ssh.rb
+++ b/lib/facter/ssh.rb
@@ -1,3 +1,12 @@
+# Fact: ssh
+#
+# Purpose:
+#
+# Resolution:
+#
+# Caveats:
+#
+
 ## ssh.rb
 ## Facts related to SSH
 ##
diff --git a/lib/facter/timezone.rb b/lib/facter/timezone.rb
index 744e06a..462c9ba 100644
--- a/lib/facter/timezone.rb
+++ b/lib/facter/timezone.rb
@@ -1,3 +1,12 @@
+# Fact: timezone
+#
+# Purpose: Return the machine's time zone.
+#
+# Resolution: Uses's Ruby's Time module's Time.new call.
+#
+# Caveats:
+#
+
 Facter.add("timezone") do
      setcode do
          Time.new.zone
diff --git a/lib/facter/uptime.rb b/lib/facter/uptime.rb
index 56a959b..7aeeb39 100644
--- a/lib/facter/uptime.rb
+++ b/lib/facter/uptime.rb
@@ -1,3 +1,14 @@
+# Fact: uptime
+#
+# Purpose: return the system uptime in a human readable format.
+#
+# Resolution:
+#   Does basic maths on the "uptime_seconds" fact to return a count of
+#   days, hours and minutes of uptime
+#
+# Caveats:
+#
+
 require 'facter/util/uptime'
 
 Facter.add(:uptime) do
diff --git a/lib/facter/uptime_days.rb b/lib/facter/uptime_days.rb
index add305c..25af966 100644
--- a/lib/facter/uptime_days.rb
+++ b/lib/facter/uptime_days.rb
@@ -1,3 +1,12 @@
+# Fact: uptime_days
+#
+# Purpose: Return purely number of days of uptime.
+#
+# Resolution: Divides uptime_hours fact by 24.
+#
+# Caveats:
+#
+
 Facter.add(:uptime_days) do
   setcode do
     hours = Facter.value(:uptime_hours)
diff --git a/lib/facter/uptime_hours.rb b/lib/facter/uptime_hours.rb
index ce691d2..d02ac32 100644
--- a/lib/facter/uptime_hours.rb
+++ b/lib/facter/uptime_hours.rb
@@ -1,3 +1,12 @@
+# Fact: uptime_hours
+#
+# Purpose: Return purely number of hours of uptime.
+#
+# Resolution: Divides uptime_seconds fact by 3600.
+#
+# Caveats:
+#
+
 Facter.add(:uptime_hours) do
   setcode do
     seconds = Facter.value(:uptime_seconds)
diff --git a/lib/facter/uptime_seconds.rb b/lib/facter/uptime_seconds.rb
index 14bb573..9793e41 100644
--- a/lib/facter/uptime_seconds.rb
+++ b/lib/facter/uptime_seconds.rb
@@ -1,3 +1,17 @@
+# Fact: uptime_seconds
+#
+# Purpose: Return purely number of seconds of uptime.
+#
+# Resolution:
+#   Using the 'facter/util/uptime.rb' module, try a verity of methods to acquire
+#   the uptime on Unix.
+#
+#   On Windows, the module calculates the uptime by the "LastBootupTime" Windows
+#   management value.
+#
+# Caveats:
+#
+
 require 'facter/util/uptime'
 
 Facter.add(:uptime_seconds) do
diff --git a/lib/facter/virtual.rb b/lib/facter/virtual.rb
index 468ab77..02802e6 100644
--- a/lib/facter/virtual.rb
+++ b/lib/facter/virtual.rb
@@ -1,3 +1,30 @@
+# Fact: virtual
+#
+# Purpose: Determine if the system's hardware is real or virtualised.
+#
+# Resolution:
+#   Assumes physical unless proven otherwise.
+#
+#   On Darwin, use the macosx util module to acquire the SPDisplaysDataType,
+#   from that parse it to see if it's VMWare or Parallels pretending to be the
+#   display.
+#
+#   On Linux, BSD, Solaris and HPUX:
+#     Much of the logic here is obscured behind util/virtual.rb, which rather
+#     than document here, which would encourage drift, just refer to it.
+#   The Xen tests in here rely on /sys and /proc, and check for the presence and
+#   contents of files in there.
+#   If after all the other tests, it's still seen as physical, then it tries to
+#   parse the output of the "lspci", "dmidecode" and "prtdiag" and parses them
+#   for obvious signs of being under VMWare or Parallels.
+#   Finally it checks for the existence of vmware-vmx, which would hint it's
+#   VMWare.
+#
+# Caveats:
+#   Virtualbox detection isn't implemented. 
+#   Many checks rely purely on existence of files.
+#
+
 require 'facter/util/virtual'
 
 Facter.add("virtual") do
@@ -108,6 +135,17 @@ Facter.add("virtual") do
     end
 end
 
+# Fact: is_virtual
+#
+# Purpose: returning true or false for if a machine is virtualised or not.
+#
+# Resolution: The Xen domain 0 machine is virtualised to a degree, but is generally
+# not viewed as being a virtual machine. This checks that the machine is not
+# physical nor xen0, if that is the case, it is virtual.
+#
+# Caveats:
+#
+
 Facter.add("is_virtual") do
     confine :kernel => %w{Linux FreeBSD OpenBSD SunOS HP-UX Darwin GNU/kFreeBSD}
 
diff --git a/lib/facter/vlans.rb b/lib/facter/vlans.rb
index d65bdd8..8c485a4 100644
--- a/lib/facter/vlans.rb
+++ b/lib/facter/vlans.rb
@@ -1,3 +1,13 @@
+# Fact: vlans
+#
+# Purpose: On Linux, return a list of all the VLANs on the system.
+#
+# Resolution: On Linux only, checks for and reads /proc/net/vlan/config and
+# parses it.
+#
+# Caveats:
+#
+
 require 'facter/util/vlans'
     
     Facter.add("vlans") do
diff --git a/lib/facter/xendomains.rb b/lib/facter/xendomains.rb
index 972ac90..5bcde05 100644
--- a/lib/facter/xendomains.rb
+++ b/lib/facter/xendomains.rb
@@ -1,3 +1,14 @@
+# Fact: xendomains
+#
+# Purpose: Return the list of Xen domains on the Dom0.
+#
+# Resolution:
+#   On a Xen Dom0 host, return a list of Xen domains using the 'util/xendomains'
+#   library.
+#
+# Caveats:
+#
+
 require 'facter/util/xendomains'
 
 Facter.add("xendomains") do