Extend ListContext to print TaskGen descriptions

Signed-off-by: Justin Israel <justinisrael@gmail.com>

playground/descriptions/wscript

@@ -0,0 +1,34 @@
+#! /usr/bin/env python
+# encoding: utf-8
+# Justin Israel, 2017 
+
+"""
+Allow the "waf list" command to display descriptions for each target
+"""
+
+top = '.'
+out = 'build'
+
+def configure(ctx):
+	pass
+
+def build(bld):
+	bld(
+		rule="touch ${TGT}",
+		target='file.in',
+		description='Create the input file',
+	)
+
+	bld(
+		rule='cp ${SRC} ${TGT}',
+		source='file.in',
+		target='file.out',
+		description='Generate output file',
+	)
+
+	bld.install_files(
+		'dist',
+		['file.out'],
+		name='install',
+		description='Deploy files',
+	)

waflib/Build.py

@@ -1295,6 +1295,10 @@ class ListContext(BuildContext):
 
 	def execute(self):
 		"""
+		In addition to printing the name of each build target,
+		a description column will include text for each task
+		generator which has a "description" field set.
+
 		See :py:func:`waflib.Build.BuildContext.execute`.
 		"""
 		self.restore()
@@ -1322,8 +1326,22 @@ class ListContext(BuildContext):
 		except Errors.WafError:
 			pass
 		
-		for k in sorted(self.task_gen_cache_names.keys()):
-			Logs.pprint('GREEN', k)
+		targets = sorted(self.task_gen_cache_names)
+
+		# figure out how much to left-justify, for largest target name
+		line_just = max(len(t) for t in targets) if targets else 0
+
+		for target in targets:
+			tgen = self.task_gen_cache_names[target]
+
+			# Support displaying the description for the target
+			# if it was set on the tgen
+			descript = getattr(tgen, 'description', None) or ''
+			if descript:
+				target = target.ljust(line_just)
+				descript = ': {}'.format(descript)
+
+			Logs.pprint('GREEN', target, label=descript)
 
 class StepContext(BuildContext):
 	'''executes tasks in a step-by-step fashion, for debugging'''

waflib/TaskGen.py

@@ -51,6 +51,11 @@ class task_gen(object):
 		self.source = []
 		self.target = ''
 
+		self.description = ''
+		"""
+		String describing the target, used for display purposes
+		"""
+
 		self.meths = []
 		"""
 		List of method names to execute (internal)