3ec23f0b6e
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.
55 lines
1.7 KiB
Ruby
55 lines
1.7 KiB
Ruby
# gendoc.rb -- Converts the top-comments inside module.c to modules API
|
|
# reference documentation in markdown format.
|
|
|
|
# Convert the C comment to markdown
|
|
def markdown(s)
|
|
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 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
|
|
}
|
|
return newlines.join("\n")
|
|
end
|
|
|
|
# Given the source code array and the index at which an exported symbol was
|
|
# detected, extracts and outputs the documentation.
|
|
def docufy(src,i)
|
|
m = /RM_[A-z0-9]+/.match(src[i])
|
|
name = m[0]
|
|
name = name.sub("RM_","RedisModule_")
|
|
proto = src[i].sub("{","").strip+";\n"
|
|
proto = proto.sub("RM_","RedisModule_")
|
|
puts "## `#{name}`\n\n"
|
|
puts " #{proto}\n"
|
|
comment = ""
|
|
while true
|
|
i = i-1
|
|
comment = src[i]+comment
|
|
break if src[i] =~ /\/\*/
|
|
end
|
|
comment = markdown(comment)
|
|
puts comment+"\n\n"
|
|
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] != '/'
|
|
if src[i-1] =~ /\*\//
|
|
docufy(src,i)
|
|
end
|
|
end
|
|
}
|