UseSWIG: Revise and format documentation

Also add some documentation of SWIG_MODULE_NAME.

Modules/UseSWIG.cmake

@@ -2,9 +2,7 @@
 # UseSWIG
 # -------
 #
-# SWIG module for CMake
-#
-# Defines the following macros:
+# Defines the following macros for use with SWIG:
 #
 # ::
 #
@@ -13,20 +11,38 @@
 #    SWIG_LINK_LIBRARIES(name [ libraries ])
 #      - Link libraries to swig module
 #
-# All other macros are for internal use only.  To get the actual name of
-# the swig module, use: ${SWIG_MODULE_${name}_REAL_NAME}.  Set Source
-# files properties such as CPLUSPLUS and SWIG_FLAGS to specify special
-# behavior of SWIG.  Also global CMAKE_SWIG_FLAGS can be used to add
-# special flags to all swig calls.  Another special variable is
-# CMAKE_SWIG_OUTDIR, it allows one to specify where to write all the
-# swig generated module (swig -outdir option) The name-specific variable
-# SWIG_MODULE_<name>_EXTRA_DEPS may be used to specify extra
-# dependencies for the generated modules.  If the source file generated
-# by swig need some special flag you can use::
+# Source files properties on module files can be set before the invocation
+# of the SWIG_ADD_MODULE macro to specify special behavior of SWIG.
 #
-#   set_source_files_properties( ${swig_generated_file_fullname}
-#         PROPERTIES COMPILE_FLAGS "-bla")
-
+# The source file property CPLUSPLUS calls SWIG in c++ mode, e.g.::
+#
+#    set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
+#    swig_add_module(mymod python mymod.i)
+#
+# The source file property SWIG_FLAGS adds custom flags to the SWIG executable.
+#
+# The source-file property SWIG_MODULE_NAME have to be provided to specify the actual
+# import name of the module in the target language if it cannot be scanned automatically
+# from source or different from the module file basename.::
+#
+#    set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
+#
+# To get the name of the swig module target library, use: ${SWIG_MODULE_${name}_REAL_NAME}.
+#
+# Also some variables can be set to specify special behavior of SWIG.
+#
+# CMAKE_SWIG_FLAGS can be used to add special flags to all swig calls.
+#
+# Another special variable is CMAKE_SWIG_OUTDIR, it allows one to specify
+# where to write all the swig generated module (swig -outdir option)
+#
+# The name-specific variable SWIG_MODULE_<name>_EXTRA_DEPS may be used to specify extra
+# dependencies for the generated modules.
+#
+# If the source file generated by swig need some special flag you can use::
+#
+#    set_source_files_properties( ${swig_generated_file_fullname}
+#                                 PROPERTIES COMPILE_FLAGS "-bla")
 
 #=============================================================================
 # Copyright 2004-2009 Kitware, Inc.