From 358d7731b2541b18c383d5694b51f68bd66e2a62 Mon Sep 17 00:00:00 2001
From: Marshall Greenblatt <magreenblatt@gmail.com>
Date: Wed, 31 Aug 2022 22:01:37 -0400
Subject: [PATCH] tools: Update translator tool for Doxygen comment format (see
 issue #3384)

Comments for translated classes/methods/functions must now take the form:

///
/// ... text ...
///
---
 tools/cef_parser.py       | 37 ++++++++++++-------------------------
 tools/make_capi_header.py |  2 +-
 2 files changed, 13 insertions(+), 26 deletions(-)

diff --git a/tools/cef_parser.py b/tools/cef_parser.py
index 3a85c1d38..047b450f6 100644
--- a/tools/cef_parser.py
+++ b/tools/cef_parser.py
@@ -99,13 +99,7 @@ def get_comment(body, name):
     line = data['line'].strip()
     pos = data['start']
     if len(line) == 0:
-      # check if the next previous line is a comment
-      prevdata = get_prev_line(body, pos)
-      prevline = prevdata['line'].strip()
-      if prevline[0:2] == '//' and prevline[0:3] != '///':
-        result.append(None)
-      else:
-        break
+      break
     # single line /*--cef()--*/
     elif line[0:2] == '/*' and line[-2:] == '*/':
       continue
@@ -119,9 +113,9 @@ def get_comment(body, name):
       continue
     elif in_block_comment:
       continue
-    elif line[0:2] == '//':
+    elif line[0:3] == '///':
       # keep the comment line including any leading spaces
-      result.append(line[2:])
+      result.append(line[3:])
     else:
       break
 
@@ -132,15 +126,9 @@ def get_comment(body, name):
 def validate_comment(file, name, comment):
   """ Validate the comment array returned by get_comment(). """
   # Verify that the comment contains beginning and ending '///' as required by
-  # CppDoc (the leading '//' from each line will already have been removed by
-  # the get_comment() logic). There may be additional comments proceeding the
-  # CppDoc block so we look at the quantity of lines equaling '/' and expect
-  # the last line to be '/'.
-  docct = 0
-  for line in comment:
-    if not line is None and len(line) > 0 and line == '/':
-      docct = docct + 1
-  if docct != 2 or len(comment) < 3 or comment[len(comment) - 1] != '/':
+  # Doxygen (the leading '///' from each line will already have been removed by
+  # the get_comment() logic).
+  if len(comment) < 3 or len(comment[0]) != 0 or len(comment[-1]) != 0:
     raise Exception('Missing or incorrect comment in %s for: %s' % \
         (file, name))
 
@@ -157,14 +145,13 @@ def format_comment(comment, indent, translate_map=None, maxchars=80):
   hasemptyline = False
   for line in comment:
     # if the line starts with a leading space, remove that space
-    if not line is None and len(line) > 0 and line[0:1] == ' ':
+    if not line is None and len(line) > 0 and line[0] == ' ':
       line = line[1:]
       didremovespace = True
     else:
       didremovespace = False
 
-    if line is None or len(line) == 0 or line[0:1] == ' ' \
-        or line[0:1] == '/':
+    if line is None or len(line) == 0 or line[0] == ' ':
       # the previous paragraph, if any, has ended
       if len(wrapme) > 0:
         if not translate_map is None:
@@ -172,14 +159,14 @@ def format_comment(comment, indent, translate_map=None, maxchars=80):
           for key in translate_keys:
             wrapme = wrapme.replace(key, translate_map[key])
         # output the previous paragraph
-        result += wrap_text(wrapme, indent + '// ', maxchars)
+        result += wrap_text(wrapme, indent + '/// ', maxchars)
         wrapme = ''
 
     if not line is None:
-      if len(line) == 0 or line[0:1] == ' ' or line[0:1] == '/':
+      if len(line) == 0 or line[0] == ' ':
         # blank lines or anything that's further indented should be
         # output as-is
-        result += indent + '//'
+        result += indent + '///'
         if len(line) > 0:
           if didremovespace:
             result += ' ' + line
@@ -200,7 +187,7 @@ def format_comment(comment, indent, translate_map=None, maxchars=80):
       for key in translate_map.keys():
         wrapme = wrapme.replace(key, translate_map[key])
     # output the previous paragraph
-    result += wrap_text(wrapme, indent + '// ', maxchars)
+    result += wrap_text(wrapme, indent + '/// ', maxchars)
 
   if hasemptyline:
     # an empty line means a break between comments, so the comment is
diff --git a/tools/make_capi_header.py b/tools/make_capi_header.py
index 52f99b936..6f11286d0 100644
--- a/tools/make_capi_header.py
+++ b/tools/make_capi_header.py
@@ -163,7 +163,7 @@ extern "C" {
     result += '\n' + format_comment(cls.get_comment(), '', translate_map)
     result += 'typedef struct _'+classname+' {\n'+\
               '  ///\n'+\
-              '  // Base structure.\n'+\
+              '  /// Base structure.\n'+\
               '  ///\n'+\
               '  '+cls.get_parent_capi_name()+' base;\n'
     funcs = cls.get_virtual_funcs()