Finished script and example output.

src/objective-c/GRPCClient/GRPCCall+OAuth2.h

@@ -33,17 +33,19 @@
 
 #import "GRPCCall.h"
 
-// Helpers for setting and reading headers compatible with OAuth2.
+/** Helpers for setting and reading headers compatible with OAuth2. */
 @interface GRPCCall (OAuth2)
 
-// Setting this property is equivalent to setting "Bearer <passed token>" as the value of the
-// request header with key "authorization" (the authorization header). Setting it to nil removes the
-// authorization header from the request.
-// The value obtained by getting the property is the OAuth2 bearer token if the authorization header
-// of the request has the form "Bearer <token>", or nil otherwise.
+/**
+ * Setting this property is equivalent to setting "Bearer <passed token>" as the value of the
+ * request header with key "authorization" (the authorization header). Setting it to nil removes the
+ * authorization header from the request.
+ * The value obtained by getting the property is the OAuth2 bearer token if the authorization header
+ * of the request has the form "Bearer <token>", or nil otherwise.
+ */
 @property(atomic, copy) NSString *oauth2AccessToken;
 
-// Returns the value (if any) of the "www-authenticate" response header (the challenge header).
+/** Returns the value (if any) of the "www-authenticate" response header (the challenge header). */
 @property(atomic, readonly) NSString *oauth2ChallengeHeader;
 
 @end

src/objective-c/change-comments.py

@@ -3,10 +3,21 @@
 import re
 import sys
 
-print 'Number of arguments:', len(sys.argv), 'arguments.'
-print 'Argument List:', str(sys.argv)
 
-with open(sys.argv[0], "r") as input_file:
+if len(sys.argv) != 2:
+  print("Please provide a source file name as only argument.")
+  quit()
+
+print("Modifying format of {file} comments in place...".format(
+    file = sys.argv[1],
+))
+
+
+# Input
+
+lines = []
+
+with open(sys.argv[1], "r") as input_file:
   lines = input_file.readlines()
 
 def peek():
@@ -15,10 +26,25 @@ def peek():
 def read_line():
   return lines.pop(0)
 
-def more_input():
+def more_input_available():
   return lines
 
 
+# Output
+
+output_lines = []
+
+def write(line):
+  output_lines.append(line)
+
+def flush_output():
+  with open(sys.argv[1], "w") as otuput_file:
+    for line in output_lines:
+      otuput_file.write(line)
+
+
+# Pattern matching
+
 comment_regex = r'^(\s*)//\s(.*)$'
 
 def is_comment(line):
@@ -28,20 +54,39 @@ def isnt_comment(line):
   return not is_comment(line)
 
 def next_line(predicate):
-  if not more_input():
+  if not more_input_available():
     return False
   return predicate(peek())
 
 
-output_lines = []
+# Transformation
 
-def output(line):
-  output_lines.append(line)
+def indentation_of(line):
+  match = re.search(comment_regex, line)
+  return match.group(1)
+
+def content(line):
+  match = re.search(comment_regex, line)
+  return match.group(2)
+
+def format_as_block(comment_block):
+  if len(comment_block) == 0:
+    return []
 
+  indent = indentation_of(comment_block[0])
 
-while more_input():
+  if len(comment_block) == 1:
+    return [indent + "/** " + content(comment_block[0]) + " */\n"]
+
+  block = ["/**"] + [" * " + content(line) for line in comment_block] + [" */"]
+  return [indent + line + "\n" for line in block]
+
+
+# Main algorithm
+
+while more_input_available():
   while next_line(isnt_comment):
-    output(read_line())
+    write(read_line())
 
   comment_block = []
   # Get all lines in the same comment block. We could restrict the indentation
@@ -50,4 +95,6 @@ def output(line):
     comment_block.append(read_line())
 
   for line in format_as_block(comment_block):
-    output(line)
+    write(line)
+
+flush_output()