Add some more in-line documentation for various Makefiles

Makefile

@@ -7,6 +7,7 @@ HERE_REL := $(notdir $(CURDIR))
 
 include Makefile.conf
 
+# YML_PATH is needed in the environment of every call to a program of the YML2 distribution
 export YML_PATH=$(YML2_PATH)
 
 .PHONY: all

Makefile.conf

@@ -3,7 +3,9 @@
 # This file may be used under the terms of the GNU General Public License version 3
 # see LICENSE.txt
 
-# To use custom build configuration variables, put them in a new file at `build-config/<name>.conf`. Execute `export PLATFORM_OVERRIDE=<name>` before running make. If this environment variable is not set, make will load a default configuration for your platform.
+# This file assembles all the make variables that a maintainer or dev may want to taylor to his or her needs on a given platform.
+
+# To use custom build configuration variables, put them in a new file with the path `build-config/<name>.conf`. Execute `export PLATFORM_OVERRIDE=<name>` before running make. If this environment variable is not set, make will load a default configuration for your platform.
 
 BUILD_CONFIG:=$(dir $(lastword $(MAKEFILE_LIST)))build-config
 

asn.1/Makefile

@@ -11,13 +11,13 @@ ALL_OBJECTS=$(subst .c,.o,$(ALL_SOURCE))
 libasn1.a: $(ALL_OBJECTS)
 	ar -rc $@ $^
 
-# "converter-sample.c" is the example file containing a "main()" function generated by ans1c.
 .PHONY: generate
 generate: Sync-Protocols.c
+	# "converter-sample.c" is the example file containing a "main()" function generated by ans1c.
 	rm -f converter-sample.c
 
-# '-Wno-cpp' is required to suppress the warning "_BSD_SOURCE and _SVID_SOURCE are deprecated, use _DEFAULT_SOURCE" otherwise printed during the compilation of every asn1c-generated C file.
 %.o: %.c %.h
+	# '-Wno-cpp' is required to suppress the warning "_BSD_SOURCE and _SVID_SOURCE are deprecated, use _DEFAULT_SOURCE" otherwise printed during the compilation of every asn1c-generated C file.
 	$(CC) $(CFLAGS) -Wno-cpp -I. $(ASN1C_INC) -c $< -o $@
 
 Sync-Protocols.c: pEp.asn1 devicegroup.asn1 protocols.asn1

build-config/common.conf

@@ -3,6 +3,8 @@
 # This file may be used under the terms of the GNU General Public License version 3
 # see LICENSE.txt
 
+# General remark: to use (only) system libraries, set all the *_INC and *_LIB variables to the empty string.
+
 ######### General #########
 BUILD_ON:=$(shell uname)
 BUILD_FOR=$(BUILD_ON)
@@ -24,12 +26,11 @@ CPPFLAGS=
 
 ######### C++ #########
 #CXX This option is platform-specific
-# CXXFLAGS is used for the tests only
 #CXXFLAGS This option is platform-specific
 
 ######### C and C++ #########
 TARGET_ARCH=
-# The following two variables will be appended to, you can thus not set them here to fixed value.
+# The following two variables will be appended to. You can thus not set them to a fixed value here.
 LDFLAGS=
 LDLIBS=
 
@@ -79,9 +80,9 @@ NETPGP_INC=
 # DEFAULT_KEYSERVER - string with default keyserver
 # CRASHDUMP_DEFAULT_LINES - number of log lines to deliver for crashdumps
 # Example:
-#    EXTRA_MACROS= -DDEFAULT_KEYSERVER=\"default-server.org\" -DCRASHDUMP_DEFAULT_LINES=23
+#    EXTRA_MACROS=-DDEFAULT_KEYSERVER=\"default-server.org\" -DCRASHDUMP_DEFAULT_LINES=23
 EXTRA_MACROS=
 
 ######### Misc #########
-# Maybe include these variables here. Check how they are used throughout the project before setting them here
+# FIXME Maybe include these variables here. Check how they are used throughout the project before setting them here
 #LLDB_BIN

src/Makefile

@@ -32,8 +32,8 @@ endif
 ifeq ($(OPENPGP),GPG)
     NO_SOURCE=pgp_netpgp.c
     CFLAGS+= -DUSE_GPG $(GPGME_INC) -DLIBGPGME=\"$(LIBGPGME)\"
-    # FIXME Why was -lgpgme commented out?
     LDFLAGS+= $(GPGME_LIB)
+    # No extra LDLIBS are needed here, because GPGME is dynamically loaded
 else ifeq ($(OPENPGP),NETPGP)
     NO_SOURCE=pgp_gpg.c
     CFLAGS+= -DUSE_NETPGP $(NETGPG_INC)
@@ -58,13 +58,11 @@ all: $(TARGET)
 	sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
 	rm -f $@.$$$$
 
-# If only the goal 'clean' is given, do not include the generated 'X.d' files.
+# If only the goal 'clean' is given, do not generate and include the '%.d' files.
 ifneq ($(MAKECMDGOALS),clean)
     -include $(DEPENDS)
 endif
 
-
-
 $(TARGET): libpEpEngine.a
 	$(CC) $(ALL_OBJECTS) $(LDFLAGS) $(LDLIBS) -o $@