Merge pull request '[jsdoc] Added editor name to examples' (#48) from fix/js-doc into hotfix/v8.3.1

Reviewed-on: https://git.onlyoffice.com/ONLYOFFICE/build_tools/pulls/48

scripts/core_common/modules/v8_89.py

@@ -23,6 +23,9 @@ def change_bootstrap():
 
   base.replaceInFile("./depot_tools/bootstrap/bootstrap.py", 
     "raise subprocess.CalledProcessError(proc.returncode, argv, None)", "return")
+
+  base.replaceInFile("./depot_tools/bootstrap/bootstrap.py", 
+    "    _win_git_bootstrap_config()", "    #_win_git_bootstrap_config()")
   
   base.writeFile("./depot_tools/bootstrap/manifest.txt", content)
   return

scripts/sdkjs_common/jsdoc/generate_docs_md.py

@@ -153,7 +153,7 @@ def generate_data_types_markdown(types, enumerations, classes, root='../../'):
     linked = [link_if_known(ts_t) for ts_t in converted]
 
     # Join them with " | "
-    param_types_md = ' | '.join(linked)
+    param_types_md = r' \| '.join(linked)
 
     # If there's still leftover angle brackets for generics, gently escape or link them
     # e.g. "Object.<string, number>" => "Object.&lt;string, number&gt;"
@@ -178,7 +178,7 @@ def generate_class_markdown(class_name, methods, properties, enumerations, class
     # Escape just before returning
     return escape_text_outside_code_blocks(content)
 
-def generate_method_markdown(method, enumerations, classes):
+def generate_method_markdown(method, enumerations, classes, example_editor_name):
     method_name = method['name']
     description = method.get('description', 'No description provided.')
     description = correct_description(description)
@@ -227,11 +227,11 @@ def generate_method_markdown(method, enumerations, classes):
         if '```js' in example:
             comment, code = example.split('```js', 1)
             comment = remove_js_comments(comment)
-            content += f"\n\n## Example\n\n{comment}\n\n```javascript\n{code.strip()}\n"
+            content += f"\n\n## Example\n\n{comment}\n\n```javascript {example_editor_name}\n{code.strip()}\n"
         else:
             # If there's no triple-backtick structure, just show it as code
             cleaned_example = remove_js_comments(example)
-            content += f"\n\n## Example\n\n```javascript\n{cleaned_example}\n```\n"
+            content += f"\n\n## Example\n\n```javascript {example_editor_name}\n{cleaned_example}\n```\n"
 
     return escape_text_outside_code_blocks(content)
 
@@ -254,7 +254,7 @@ def generate_properties_markdown(properties, enumerations, classes, root='../'):
     # Escape outside code blocks
     return escape_text_outside_code_blocks(content)
 
-def generate_enumeration_markdown(enumeration, enumerations, classes):
+def generate_enumeration_markdown(enumeration, enumerations, classes, example_editor_name):
     enum_name = enumeration['name']
     description = enumeration.get('description', 'No description provided.')
     description = correct_description(description)
@@ -300,11 +300,11 @@ def generate_enumeration_markdown(enumeration, enumerations, classes):
         if '```js' in example:
             comment, code = example.split('```js', 1)
             comment = remove_js_comments(comment)
-            content += f"\n\n## Example\n\n{comment}\n\n```javascript\n{code.strip()}\n"
+            content += f"\n\n## Example\n\n{comment}\n\n```javascript {example_editor_name}\n{code.strip()}\n"
         else:
             # If there's no triple-backtick structure
             cleaned_example = remove_js_comments(example)
-            content += f"\n\n## Example\n\n```javascript\n{cleaned_example}\n```\n"
+            content += f"\n\n## Example\n\n```javascript {example_editor_name}\n{cleaned_example}\n```\n"
 
     return escape_text_outside_code_blocks(content)
 
@@ -313,6 +313,16 @@ def process_doclets(data, output_dir, editor_name):
     classes_props = {}
     enumerations = []
     editor_dir =  os.path.join(output_dir, editor_name)
+    example_editor_name = 'editor-'
+    
+    if editor_name == 'Word':
+        example_editor_name += 'docx'
+    elif editor_name == 'Forms':
+        example_editor_name += 'pdf'
+    elif editor_name == 'Slide':
+        example_editor_name += 'pptx'
+    elif editor_name == 'Cell':
+        example_editor_name += 'xlsx'
 
     for doclet in data:
         if doclet['kind'] == 'class':
@@ -347,7 +357,7 @@ def process_doclets(data, output_dir, editor_name):
         # Write method files
         for method in methods:
             method_file_path = os.path.join(methods_dir, f"{method['name']}.md")
-            method_content = generate_method_markdown(method, enumerations, classes)
+            method_content = generate_method_markdown(method, enumerations, classes, example_editor_name)
             write_markdown_file(method_file_path, method_content)
 
             if not method.get('example', ''):
@@ -359,7 +369,7 @@ def process_doclets(data, output_dir, editor_name):
 
     for enum in enumerations:
         enum_file_path = os.path.join(enum_dir, f"{enum['name']}.md")
-        enum_content = generate_enumeration_markdown(enum, enumerations, classes)
+        enum_content = generate_enumeration_markdown(enum, enumerations, classes, example_editor_name)
         if enum_content is None:
             continue
 

scripts/sdkjs_common/jsdoc/generate_docs_plugins_md.py

@@ -153,7 +153,7 @@ def generate_data_types_markdown(types, enumerations, classes, root='../../'):
     linked = [link_if_known(ts_t) for ts_t in converted]
 
     # Join them with " | "
-    param_types_md = ' | '.join(linked)
+    param_types_md = r' \| '.join(linked)
 
     # If there's still leftover angle brackets for generics, gently escape or link them
     # e.g. "Object.<string, number>" => "Object.&lt;string, number&gt;"
@@ -178,7 +178,7 @@ def generate_class_markdown(class_name, methods, properties, enumerations, class
     # Escape just before returning
     return escape_text_outside_code_blocks(content)
 
-def generate_method_markdown(method, enumerations, classes):
+def generate_method_markdown(method, enumerations, classes, example_editor_name):
     """
     Generates Markdown for a method doclet, relying only on `method['examples']`
     (array of strings). Ignores any single `method['example']` field.
@@ -247,12 +247,12 @@ def generate_method_markdown(method, enumerations, classes):
                 if len(examples) > 1:
                     content += f"**Example {i}:**\n\n{comment}\n\n"
                 
-                content += f"```javascript\n{code}\n```\n"
+                content += f"```javascript {example_editor_name}\n{code}\n```\n"
             else:
                 if len(examples) > 1:
                     content += f"**Example {i}:**\n\n{comment}\n\n"
                 # No special fences, just show as code
-                content += f"```javascript\n{cleaned_example}\n```\n"
+                content += f"```javascript {example_editor_name}\n{cleaned_example}\n```\n"
 
     return escape_text_outside_code_blocks(content)
 
@@ -275,7 +275,7 @@ def generate_properties_markdown(properties, enumerations, classes, root='../'):
     # Escape outside code blocks
     return escape_text_outside_code_blocks(content)
 
-def generate_enumeration_markdown(enumeration, enumerations, classes):
+def generate_enumeration_markdown(enumeration, enumerations, classes, example_editor_name):
     """
     Generates Markdown documentation for a 'typedef' doclet.
     This version only works with `enumeration['examples']` (an array of strings),
@@ -354,12 +354,12 @@ def generate_enumeration_markdown(enumeration, enumerations, classes):
                 if len(examples) > 1:
                     content += f"**Example {i}:**\n\n{comment}\n\n"
                 
-                content += f"```javascript\n{code}\n```\n"
+                content += f"```javascript {example_editor_name}\n{code}\n```\n"
             else:
                 if len(examples) > 1:
                     content += f"**Example {i}:**\n\n{comment}\n\n"
                 # No special fences, just show as code
-                content += f"```javascript\n{cleaned_example}\n```\n"
+                content += f"```javascript {example_editor_name}\n{cleaned_example}\n```\n"
 
     return escape_text_outside_code_blocks(content)
 
@@ -368,6 +368,16 @@ def process_doclets(data, output_dir, editor_name):
     classes_props = {}
     enumerations = []
     editor_dir =  os.path.join(output_dir, editor_name)
+    example_editor_name = 'editor-'
+    
+    if editor_name == 'Word':
+        example_editor_name += 'docx'
+    elif editor_name == 'Forms':
+        example_editor_name += 'pdf'
+    elif editor_name == 'Slide':
+        example_editor_name += 'pptx'
+    elif editor_name == 'Cell':
+        example_editor_name += 'xlsx'
 
     for doclet in data:
         if doclet['kind'] == 'class':
@@ -402,7 +412,7 @@ def process_doclets(data, output_dir, editor_name):
         # Write method files
         for method in methods:
             method_file_path = os.path.join(methods_dir, f"{method['name']}.md")
-            method_content = generate_method_markdown(method, enumerations, classes)
+            method_content = generate_method_markdown(method, enumerations, classes, example_editor_name)
             write_markdown_file(method_file_path, method_content)
 
             if not method.get('examples', ''):
@@ -414,7 +424,7 @@ def process_doclets(data, output_dir, editor_name):
 
     for enum in enumerations:
         enum_file_path = os.path.join(enum_dir, f"{enum['name']}.md")
-        enum_content = generate_enumeration_markdown(enum, enumerations, classes)
+        enum_content = generate_enumeration_markdown(enum, enumerations, classes, example_editor_name)
         if enum_content is None:
             continue
 

version

@@ -1 +1 @@
-8.2.2
+8.3.0