Commit ebf20b83 authored by Viktor Söderqvist's avatar Viktor Söderqvist Committed by Oran Agra
Browse files

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.
parent 108afbc0
This diff is collapsed.
...@@ -4,16 +4,18 @@ ...@@ -4,16 +4,18 @@
# Convert the C comment to markdown # Convert the C comment to markdown
def markdown(s) def markdown(s)
s = s.gsub(/\*\/$/,"") 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] == " " s.chop! while s[-1] == "\n" || s[-1] == " "
lines = s.split("\n") lines = s.split("\n")
newlines = [] newlines = []
# Backquote function, macro and type names, except if already backquoted and
# in code blocks indented by 4 spaces.
lines.each{|l| lines.each{|l|
if l[0] != ' ' if not l.start_with?(' ')
l = l.gsub(/RM_[A-z()]+/){|x| "`#{x}`"} l = l.gsub(/(?<!`)RM_[A-z()]+/){|x| "`#{x}`"}
l = l.gsub(/RedisModule_[A-z()]+/){|x| "`#{x}`"} l = l.gsub(/(?<!`)RedisModule[A-z()]+/){|x| "`#{x}`"}
l = l.gsub(/REDISMODULE_[A-z]+/){|x| "`#{x}`"} l = l.gsub(/(?<!`)REDISMODULE_[A-z]+/){|x| "`#{x}`"}
end end
newlines << l newlines << l
} }
...@@ -41,6 +43,7 @@ def docufy(src,i) ...@@ -41,6 +43,7 @@ def docufy(src,i)
end end
puts "# Modules API reference\n\n" 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 = File.open("../module.c").to_a
src.each_with_index{|line,i| src.each_with_index{|line,i|
if line =~ /RM_/ && line[0] != ' ' && line[0] != '#' && line[0] != '/' if line =~ /RM_/ && line[0] != ' ' && line[0] != '#' && line[0] != '/'
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment