api: Make some comments NaturalDocs-compatible.

In the process of trying to plan out the best way to fix the issue where
module names passed on the command line that are implicit subprojects of
a kde-projects module go unrecognized, I decided that I needed a better
way to navigate the API.

There is a Doxygen::Filter::Perl available which seems decent as it
allows one to use the nice and familiar Doxygen tool, but it seems a bit
buggy still.

NaturalDocs is a tool which seems better able to cope with kdesrc-build
and its code, although it prefers comments to be formatted unlike the
normal qdoc/JavaDoc syntax used by Doxygen. However it's not that much
different and is easier to install and use otherwise. Maybe when I get
some time I'll go ahead and properly convert everything.

kdesrc-build

@@ -94,10 +94,18 @@ my $run_mode = 'build'; # Determines if updating, building, installing, etc.
 
 # }}}
 
-# Moves the directory given by the first parameter to be at the directory given
-# by the second parameter, but only if the first exists and the second doesn't.
+# Function: moveOldDirectories
+# Moves a directory to a new location, but only if the new location doesn't
+# already exist.
 # The use case is to automatically migrate source and build directories from
 # the change in dest-dir handling for XML-based modules.
+#
+# Parameters:
+#  oldDir - The directory to move.
+#  newDir - The name the directory should have afterwards.
+#
+# Returns:
+#  Boolean true, but throws an exception on error.
 sub moveOldDirectories
 {
     my ($oldDir, $newDir) = @_;
@@ -117,25 +125,36 @@ sub moveOldDirectories
     return 1;
 }
 
-# Subroutine to return the directory that a module will be stored in.
+# Function: get_module_path_dir
+#
+# Returns the directory that a module will be stored in.
+#
 # NOTE: The return value is a hash. The key 'module' will return the final
 # module name, the key 'path' will return the full path to the module. The
 # key 'fullpath' will return their concatenation.
+#
 # For example, with $module == 'KDE/kdelibs', and no change in the dest-dir
 # option, you'd get something like:
-# {
-#   'path'     => '/home/user/kdesrc/KDE',
-#   'module'   => 'kdelibs',
-#   'fullpath' => '/home/user/kdesrc/KDE/kdelibs'
-# }
+#
+# > {
+# >   'path'     => '/home/user/kdesrc/KDE',
+# >   'module'   => 'kdelibs',
+# >   'fullpath' => '/home/user/kdesrc/KDE/kdelibs'
+# > }
 # If dest-dir were changed to e.g. extragear-multimedia, you'd get:
-# {
-#   'path'     => '/home/user/kdesrc',
-#   'module'   => 'extragear-multimedia',
-#   'fullpath' => '/home/user/kdesrc/extragear-multimedia'
-# }
-# First parameter is the module.
-# Second parameter is either source or build.
+#
+# > {
+# >   'path'     => '/home/user/kdesrc',
+# >   'module'   => 'extragear-multimedia',
+# >   'fullpath' => '/home/user/kdesrc/extragear-multimedia'
+# > }
+#
+# Parameters:
+#   module - The <Module>.
+#   pathType - Either 'source' or 'build'.
+#
+# Returns:
+#   hash (Not a hashref; See description).
 sub get_module_path_dir
 {
     my $module = assert_isa(shift, 'ksb::Module');

modules/ksb/Module.pm

@@ -1,8 +1,10 @@
 package ksb::Module;
 
-# Class representing a source code module of some sort, which can be updated, built,
-# and installed. Includes a stringifying overload and can be sorted amongst other
-# ksb::Modules.
+# Class: Module
+#
+# Represents a source code module of some sort, which can be updated, built,
+# and installed. Includes a stringifying overload and can be sorted amongst
+# other ksb::Modules.
 
 use strict;
 use warnings;