From ebf20b83b2cfcaf326f037a8274848662a3a9603 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Viktor=20S=C3=B6derqvist?= <viktor.soderqvist@est.tech>
Date: Wed, 13 Jan 2021 15:14:51 +0100
Subject: Modules API reference formatting fixes

Fixes markdown formatting errors and some functions not showing
up in the generated documentation at all.

Ruby script (gendoc.rb) fixes:

* Modified automatic instertion of backquotes:
  * Don't add backquotes around names which are already preceded by a
    backquote. Fixes for example \`RedisModule_Reply\*\` which turning
    into \`\`RedisModule_Reply\`\*\` messes up the formatting.
  * Add backquotes around types such as RedisModuleString (in addition
    to function names `RedisModule_[A-z()]*` and macro names
    `REDISMODULE_[A-z]*`).
  * Require 4 spaces indentation for disabling automatic backquotes, i.e.
    code blocks. Fixes continuations of list items (indented 2 spaces).
* More permissive extraction of doc comments:
  * Allow doc comments starting with `/**`.
  * Make space before `*` on each line optional.
  * Make space after `/*` and `/**` optional (needed when appearing on
    its own line).

Markdown fixes in module.c:

* Fix code blocks not indented enough (4 spaces needed).
* Add black line before code blocks and lists where missing (needed).
* Enclose special markdown characters `_*^<>` in backticks to prevent them
  from messing up formatting.
* Lists with `1)` changed to `1.` for proper markdown lists.
* Remove excessive indentation which causes text to be unintentionally
  rendered as code blocks.
* Other minor formatting fixes.

Other fixes in module.c:

* Remove blank lines between doc comment and function definition. A blank
  line here makes the Ruby script exclude the function in docs.
---
 src/modules/gendoc.rb | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'src/modules')

diff --git a/src/modules/gendoc.rb b/src/modules/gendoc.rb
index ee6572884..249c8b6ea 100644
--- a/src/modules/gendoc.rb
+++ b/src/modules/gendoc.rb
@@ -4,16 +4,18 @@
 # Convert the C comment to markdown
 def markdown(s)
     s = s.gsub(/\*\/$/,"")
-    s = s.gsub(/^ \* {0,1}/,"")
-    s = s.gsub(/^\/\* /,"")
+    s = s.gsub(/^ ?\* ?/,"")
+    s = s.gsub(/^\/\*\*? ?/,"")
     s.chop! while s[-1] == "\n" || s[-1] == " "
     lines = s.split("\n")
     newlines = []
+    # Backquote function, macro and type names, except if already backquoted and
+    # in code blocks indented by 4 spaces.
     lines.each{|l|
-        if l[0] != ' '
-            l = l.gsub(/RM_[A-z()]+/){|x| "`#{x}`"}
-            l = l.gsub(/RedisModule_[A-z()]+/){|x| "`#{x}`"}
-            l = l.gsub(/REDISMODULE_[A-z]+/){|x| "`#{x}`"}
+        if not l.start_with?('    ')
+            l = l.gsub(/(?<!`)RM_[A-z()]+/){|x| "`#{x}`"}
+            l = l.gsub(/(?<!`)RedisModule[A-z()]+/){|x| "`#{x}`"}
+            l = l.gsub(/(?<!`)REDISMODULE_[A-z]+/){|x| "`#{x}`"}
         end
         newlines << l
     }
@@ -41,6 +43,7 @@ def docufy(src,i)
 end
 
 puts "# Modules API reference\n\n"
+puts "<!-- This file is generated from module.c using gendoc.rb -->\n\n"
 src = File.open("../module.c").to_a
 src.each_with_index{|line,i|
     if line =~ /RM_/ && line[0] != ' ' && line[0] != '#' && line[0] != '/'
-- 
cgit v1.2.1