Remove bloody submodules.

5 files changed, 567 insertions, 0 deletions

diff --git a/doc/doxydown b/doc/doxydown
deleted file mode 160000
-Subproject 6c1f79c4294ef66a55bfc75845f3fdf3e2e1c32
diff --git a/doc/doxydown/.gitignore b/doc/doxydown/.gitignore
new file mode 100644
index 000000000..eaca02ed3
--- /dev/null
+++ b/doc/doxydown/.gitignore
@@ -0,0 +1,19 @@
+/blib/
+/.build/
+_build/
+cover_db/
+inc/
+Build
+!Build/
+Build.bat
+.last_cover_stats
+/Makefile
+/Makefile.old
+/MANIFEST.bak
+/META.yml
+/META.json
+/MYMETA.*
+nytprof.out
+/pm_to_blib
+*.o
+*.bs
diff --git a/doc/doxydown/LICENSE b/doc/doxydown/LICENSE
new file mode 100644
index 000000000..d39277a3e
--- /dev/null
+++ b/doc/doxydown/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Vsevolod Stakhov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/doc/doxydown/README.md b/doc/doxydown/README.md
new file mode 100644
index 000000000..fb3f9f14b
--- /dev/null
+++ b/doc/doxydown/README.md
@@ -0,0 +1,139 @@
+# Doxydown - documentation utility
+
+## Introduction
+
+Doxydown is an utility to convert `doxygen`-like comments from the source code to markdown.
+Unlike other documentation systems, `doxydown` is specifically designed to generate markdown output only.
+At the moment, doxydown can work with C and lua comments and produce kramdown/pandoc or github
+flavoured markdown. Doxydown produces output with anchors, links and table of content.
+It also can highlight syntax for examples in the documentation.
+
+### Why markdown
+
+Markdown is used by many contemporary engines and can be rendered to HTML using
+advanced templates, styles and scripts. Markdown provides excellent formatting
+capabilities while it doesn't require authors to be web designers to create
+documentation. Markdown is rendered by [`github`](https://github.com) and
+doxydown can generate documentation easily viewed directly inside github. Moreover,
+doxydown supports pandoc style of markdown and that means that markdown output 
+can be converted to all formats supported by pandoc (html, pdf, latex,
+man pages and many others).
+
+### Why not `other documentation generator`
+
+Doxydown is extremely simple as it can output markdown only but it is very
+convenient tool to generate nice markdown with all features required from the
+documentation system. Doxydown uses input format that is very close to `doxygen`
+that allows to re-use the existing documentation comments. Currenly, doxydown
+does not support many features but they could be easily added on demand.
+
+## Input format
+
+Doxydown extracts documentation from the comments blocks. The start of block is indicated by
+
+	/***  
+
+in `C` or by
+
+	--[[[
+
+in `lua`. The end of documentation block is the normal multiline comment ending
+specific for the input language. Doxydown also strips an initial comment character,
+therefore the following inputs are equal:
+
+~~~c
+/***
+ * some text
+ * other text
+ *
+ */
+~~~
+and
+
+~~~c
+/***
+some text
+other text
+
+*/
+~~~
+
+Note that doxydown preserves empty lines and all markdown elements.
+
+### Documentation blocks
+
+Each documentation block describes either module or function/method. Modules are
+logical compounds of functions and methods. The difference between method and
+function is significant for languages with methods support (e.g. by `lua` via
+metatables). To define method or function you can use the following:
+
+	/***
+	@function my_awesome_function(param1[, param2])
+	This function is awesome.
+	*/ 
+
+All text met in the current documentation block is used as function or method description.
+You can also define parameters and return values for functions and methods:
+
+	@param {type} param1 mandatory param
+
+Here, `{type}` is optional type description for a parameter, `param1` is parameter's name
+and the rest of the string is parameter description. Currently, you cannot split
+parameter description by newline character. In future versions of doxydown this might
+be fixed.
+
+You can specify return type of your function by using of `@return` tag:
+
+	@return {type} some cool result
+	
+This tag is similar to `@param` and has the same limitation regarding newlines.
+You can also add some example code by using of `@example` tag:
+
+	@example
+	my_awesome_function('hello'); // returns 42
+
+All text after `@example` tag and until documentation block end is used as an example
+and is highlighted in markdown. Also you can switch the language of example by using
+the extended `@example` tag:
+
+	@example lua
+
+In this example, the code will be highlighted as `lua` code.
+
+Modules descriptions uses the same conventions, but `@param` and `@return` are
+meaningless for the modules. Function and methods blocks that follows some `@module`
+block are automatically attached to that module.
+
+Both modules and function can use links to other functions and methods by using of
+`@see` tag:
+
+	@see my_awesome_function
+
+This inserts a hyperlink to the specified function definition to the markdown.
+
+## Output format
+
+Doxydown can generate github flavoured markdown and pandoc/kramdown compatible
+markdown. The main difference is in how anchors are organized. In kramdown and
+pandoc it is possible to specify an explicit id for each header, whilst in
+GH flavoured markdown we can use only implicit anchors.
+
+### Examples
+
+You can see an example of github flavoured markdown render at 
+[libucl github page](https://github.com/vstakhov/libucl/blob/master/doc/lua_api.md).
+The same page bu rendered by kramdown engine in `jekyll` platform can be 
+accessed by [this address](https://rspamd.com/doc/lua/ucl.html).
+
+## Program invocation
+
+	doxydown [-hg] [-l language] < input_source > markdown.md
+
+* `-h`: help message
+* `-e`: sets default example language (default: lua)
+* `-l`: sets input language (default: c)
+* `-g`: use github flavoured markdown (default: kramdown/pandoc)
+
+## License
+
+Doxydown is published by terms of `MIT` license.
\ No newline at end of file
diff --git a/doc/doxydown/doxydown.pl b/doc/doxydown/doxydown.pl
new file mode 100755
index 000000000..3aa1b6b1d
--- /dev/null
+++ b/doc/doxydown/doxydown.pl
@@ -0,0 +1,388 @@
+#!/usr/bin/env perl
+
+$VERSION = "0.1";
+
+use strict;
+use warnings;
+use Data::Dumper;
+use Digest::MD5 qw(md5_hex);
+
+my @modules;
+my %options = ();
+my $cur_module;
+my $example_language = "lua";
+
+my %languages = (
+    c => {
+        start  => qr/^\s*\/\*\*\*(?:\s*|(\s+\S.+\s*))$/,
+        end    => qr/^\s*\*+\/\s*$/,
+        filter => qr/^(?:\s*\*+\s?)?(\s*[^*].+)\s*$/,
+    },
+    lua => {
+        start  => qr/^\s*\--\[\[\[\s*$/,
+        end    => qr/^\s*--\]\]\s*/,
+        filter => qr/^(?:\s*--\s)?(\s*\S.+)\s*$/,
+    },
+);
+
+my $function_re = qr/^\s*\@(function|fn|method)\s*(\S.+)$/oi;
+my $module_re = qr/^\s*\@(?:module|file)\s*(\S.+)$/oi;
+
+my $language;
+
+sub print_module_markdown {
+    my ( $mname, $m ) = @_;
+
+    my $idline = $options{g} ? "" : " {#$m->{'id'}}";
+    print <<EOD;
+## Module `$mname`$idline
+
+$m->{'data'}
+EOD
+    if ( $m->{'example'} ) {
+        print <<EOD;
+
+Example:
+
+~~~$m->{'example_language'}
+$m->{'example'}
+~~~
+EOD
+    }
+
+    sub print_func {
+        my ($f) = @_;
+
+        my $name = $f->{'name'};
+        my $id   = $f->{'id'};
+        if ($f->{'brief'}) {
+            print "> [`$name`](#$id): ". $f->{'brief'} . "\n\n";
+        }
+        else {
+            print "> [`$name`](#$id)\n\n";
+        }
+    }
+
+    print "\n### Brief content:\n\n";
+    if (scalar(@{ $m->{'functions'} }) > 0) {
+        print "**Functions**:\n\n";
+        foreach ( @{ $m->{'functions'} } ) {
+        print_func($_);
+        }
+    }
+    if (scalar(@{ $m->{'methods'} }) > 0) {
+        print "\n\n**Methods**:\n\n";
+        foreach (@{ $m->{'methods'} }) {
+            print_func($_);
+        }
+    }
+}
+
+sub print_function_markdown {
+    my ( $type, $fname, $f ) = @_;
+
+    my $idline = $options{g} ? "" : " {#$f->{'id'}}";
+    print <<EOD;
+### $type `$fname`$idline
+
+$f->{'data'}
+EOD
+    print "\n**Parameters:**\n\n";
+    if ( $f->{'params'} && scalar @{ $f->{'params'} } > 0 ) {
+        foreach ( @{ $f->{'params'} } ) {
+            if ( $_->{'type'} ) {
+                print
+                    "- `$_->{'name'} \{$_->{'type'}\}`: $_->{'description'}\n";
+            }
+            else {
+                print "- `$_->{'name'}`: $_->{'description'}\n";
+            }
+        }
+    }
+    else {
+        print "\tnothing\n";
+    }
+    print "\n**Returns:**\n\n";
+    if ( $f->{'return'} && $f->{'return'}->{'description'} ) {
+        $_ = $f->{'return'};
+        if ( $_->{'type'} ) {
+            print "- `\{$_->{'type'}\}`: $_->{'description'}\n";
+        }
+        else {
+            print "- $_->{'description'}\n";
+        }
+    }
+    else {
+        print "\tnothing\n";
+    }
+    if ( $f->{'example'} ) {
+        print <<EOD;
+
+Example:
+
+~~~$f->{'example_language'}
+$f->{'example'}
+~~~
+EOD
+    }
+}
+
+sub print_markdown {
+    for my $m (@modules) {
+        my $mname = $m->{name};
+        print_module_markdown( $mname, $m );
+
+        if (scalar(@{ $m->{'functions'} }) > 0) {
+            print
+                "\n## Functions\n\nThe module `$mname` defines the following functions.\n\n";
+            foreach (@{ $m->{'functions'} }) {
+                print_function_markdown( "Function", $_->{'name'}, $_ );
+                print "\nBack to [module description](#$m->{'id'}).\n\n";
+
+            }
+        }
+
+        if (scalar(@{ $m->{'methods'} }) > 0) {
+            print
+                "\n## Methods\n\nThe module `$mname` defines the following methods.\n\n";
+            foreach (@{ $m->{'methods'} }) {
+                print_function_markdown( "Method", $_->{'name'}, $_ );
+                print "\nBack to [module description](#$m->{'id'}).\n\n";
+
+            }
+        }
+
+        print "\nBack to [top](#).\n\n";
+    }
+}
+
+sub make_id {
+    my ( $name, $prefix ) = @_;
+
+    if ( !$prefix ) {
+        $prefix = "f";
+    }
+    if ( !$options{g} ) {
+
+        # Kramdown/pandoc version of ID's
+        $name =~ /^(\S+).*$/;
+        return substr( substr( $prefix, 0, 1 ) . md5_hex($1), 0, 6 );
+    }
+    else {
+        my $input = lc $prefix . "-" . $name;
+        my $id = join '-', split /\s+/, $input;
+        $id =~ s/[^\w_-]+//g;
+        return $id;
+    }
+}
+
+sub substitute_data_keywords {
+    my ($line) = @_;
+
+    if ( $line =~ /^.*\@see\s+(\S+)\s*.*$/ ) {
+        my $name = $1;
+        my $id   = make_id($name);
+        return $line =~ s/\@see\s+\S+/[`$name`](#$id)/r;
+    }
+
+    return $line;
+}
+
+sub parse_function {
+    my ( $func, @data ) = @_;
+
+    my ( $type, $name ) = ( $func =~ $function_re );
+
+    chomp $name;
+
+    my $f = {
+        name             => $name,
+        data             => '',
+        example          => undef,
+        example_language => $example_language,
+        id               => make_id( $name, $type ),
+    };
+    my $example = 0;
+
+    foreach (@data) {
+        if (/^\s*\@param\s*(?:\{([^}]+)\})?\s*(\S+)\s*(.+)?\s*$/) {
+            my $p = { name => $2, type => $1, description => $3 };
+            push @{ $f->{'params'} }, $p;
+        }
+        elsif (/^\s*\@return\s*(?:\{([^}]+)\})?\s*(.+)?\s*$/) {
+            my $r = { type => $1, description => $2 };
+            $f->{'return'} = $r;
+        }
+        elsif (/^\s*\@brief\s*(\S.+)$/) {
+            $f->{'brief'} = $1;
+        }
+        elsif (/^\s*\@example\s*(\S)?\s*$/) {
+            $example = 1;
+            if ($1) {
+                $f->{'example_language'} = $1;
+            }
+        }
+        elsif ( $_ ne $func ) {
+            if ($example) {
+                $f->{'example'} .= $_;
+            }
+            else {
+                $f->{'data'} .= substitute_data_keywords($_);
+            }
+        }
+    }
+    if ( $f->{'data'} ) {
+        chomp $f->{'data'};
+    }
+    elsif ($f->{'brief'}) {
+        chomp $f->{'brief'};
+        $f->{'data'} = $f->{'brief'};
+    }
+    if ( $f->{'example'} ) {
+        chomp $f->{'example'};
+    }
+
+    if ( $type eq "method" ) {
+        push @{ $cur_module->{'methods'} }, $f;
+    }
+    else {
+        push @{ $cur_module->{'functions'} }, $f;
+    }
+}
+
+sub parse_module {
+    my ( $module, @data ) = @_;
+    my ( $name ) = ( $module =~ $module_re );
+
+    chomp $name;
+
+    my $f = {
+        name             => $name,
+        functions        => [],
+        methods          => [],
+        data             => '',
+        example          => undef,
+        example_language => $example_language,
+        id               => make_id( $name, "module" ),
+    };
+    my $example = 0;
+
+    foreach (@data) {
+        if (/^\s*\@example\s*(\S)?\s*$/) {
+            $example = 1;
+            if ($1) {
+                $f->{'example_language'} = $1;
+            }
+        }
+        elsif (/^\s*\@brief\s*(\S.+)$/) {
+            $f->{'brief'} = $1;
+        }
+        elsif ( $_ ne $module ) {
+            if ($example) {
+                $f->{'example'} .= $_;
+            }
+            else {
+                $f->{'data'} .= substitute_data_keywords($_);
+            }
+        }
+    }
+    if ( $f->{'data'} ) {
+        chomp $f->{'data'};
+    }
+    elsif ($f->{'brief'}) {
+        chomp $f->{'brief'};
+        $f->{'data'} = $f->{'brief'};
+    }
+    if ( $f->{'example'} ) {
+        chomp $f->{'example'};
+    }
+    $cur_module = $f;
+    push @modules, $f;
+}
+
+sub parse_content {
+    my @func = grep /$function_re/, @_;
+    if ( scalar @func > 0 ) {
+        parse_function( $func[0], @_ );
+    }
+
+    my @module = grep /$module_re/, @_;
+    if ( scalar @module > 0 ) {
+        parse_module( $module[0], @_ );
+    }
+}
+
+sub HELP_MESSAGE {
+    print STDERR <<EOF;
+Utility to convert doxygen comments to markdown.
+
+usage: $0 [-hg] [-l language] < input_source > markdown.md
+
+ -h        : this (help) message
+ -e        : sets default example language (default: lua)
+ -l        : sets input language (default: c)
+ -g        : use github flavoured markdown (default: kramdown/pandoc)
+EOF
+    exit;
+}
+
+$Getopt::Std::STANDARD_HELP_VERSION = 1;
+use Getopt::Std;
+getopts( 'he:gl:', \%options );
+
+HELP_MESSAGE() if $options{h};
+
+$example_language = $options{e} if $options{e};
+$language = $languages{ lc $options{l} } if $options{l};
+
+if ( !$language ) {
+    $language = $languages{c};
+}
+
+use constant {
+    STATE_READ_SKIP    => 0,
+    STATE_READ_CONTENT => 1,
+    STATE_READ_ENUM => 2,
+    STATE_READ_STRUCT => 3,
+};
+
+my $state = STATE_READ_SKIP;
+my $content;
+
+while (<>) {
+    if ( $state == STATE_READ_SKIP ) {
+        if ( $_ =~ $language->{start} ) {
+            $state = STATE_READ_CONTENT;
+            if (defined($1)) {
+                chomp($content = $1);
+                $content =~ tr/\r//d;
+                $content .= "\n";
+            }
+            else {
+                $content = "";
+            }
+        }
+    }
+    elsif ( $state == STATE_READ_CONTENT ) {
+        if ( $_ =~ $language->{end} ) {
+            $state = STATE_READ_SKIP;
+            parse_content( split /^/, $content );
+            $content = "";
+        }
+        else {
+            my ($line) = ( $_ =~ $language->{filter} );
+
+            if ($line) {
+                $line =~ tr/\r//d;
+                $content .= $line . "\n";
+            }
+            else {
+                # Preserve empty lines
+                $content .= "\n";
+            }
+        }
+    }
+}
+
+#print Dumper( \@modules );
+print_markdown;