reference documentation cleanup

docs/gen_reference_doc.py

@@ -146,12 +146,19 @@ def highlight_signature(s):
 
 	# make the name of the function bold
 	name2[-1] = '**' + name2[-1] + '** '
-	name2[0] = name2[0].replace('*', '\\*')
+
+	# if there is a return value, make sure we preserve pointer types
+	if len(name2) > 1:
+		name2[0] = name2[0].replace('*', '\\*')
 	name[0] = ' '.join(name2)
 
 	# we have to escape asterisks, since this is rendered into
 	# a parsed literal in rst
 	name[1] = name[1].replace('*', '\\*')
+
+	# comments in signatures are italic
+	name[1] = name[1].replace('/\\*', '*/\\*')
+	name[1] = name[1].replace('\\*/', '\\*/*')
 	return '('.join(name)
 
 def html_sanitize(s):
@@ -756,25 +763,28 @@ def linkify_symbols(string):
 			in_literal = True
 		words = l.split(' ')
 
-		if len(words) == 1:
-			ret.append(l)
-			continue
-
 		for i in range(len(words)):
 			# it's important to preserve leading
 			# tabs, since that's relevant for
 			# rst markup
-			leading_tabs = 0
-			while leading_tabs < len(words[i]) and words[i][leading_tabs] == '\t':
-				leading_tabs += 1
+
+			leading = ''
+			w = words[i]
+
+			if len(w) == 0: continue
+
+			while len(w) > 0 and \
+				w[0] in ['\t', ' ', '(', '[', '{']:
+				leading += w[0]
+				w = w[1:]
 
 			# preserve commas and dots at the end
-			w = words[i].strip()
+			w = w.strip()
 			trailing = ''
 
 			if len(w) == 0: continue
 
-			while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')):
+			while len(w) > 1 and w[-1] in ['.', ',', ')'] and w[-2:] != '()':
 				trailing = w[-1] + trailing
 				w = w[:-1]
 
@@ -789,7 +799,7 @@ def linkify_symbols(string):
 			if w in symbols:
 				link_name = link_name.replace('-', ' ')
 #				print '  found %s -> %s' % (w, link_name)
-				words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
+				words[i] = leading + print_link(link_name, symbols[w]) + trailing
 		ret.append(' '.join(words))
 	return '\n'.join(ret)