kernel-doc

ARM 嵌入式 系统 设计与实例开发 实验教材 二源码

    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>".$args{'function'}."</refname>\n";
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <funcsynopsis><funcprototype>\n";
    print "   <funcdef>".$args{'functiontype'}." ";
    print "<function>".$args{'function'}." </function></funcdef>\n";

    $count = 0;
    if ($#{$args{'parameterlist'}} >= 0) {
	foreach $parameter (@{$args{'parameterlist'}}) {
	    $type = $args{'parametertypes'}{$parameter};
	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
		# pointer-to-function
		print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
		print "     <funcparams>$2</funcparams></paramdef>\n";
	    } else {
		print "   <paramdef>".$type;
		print " <parameter>$parameter</parameter></paramdef>\n";
	    }
	}
    } else {
	print "  <void>\n";
    }
    print "  </funcprototype></funcsynopsis>\n";
    print "</refsynopsisdiv>\n";

    # print parameters
    print "<refsect1>\n <title>Arguments</title>\n";
    if ($#{$args{'parameterlist'}} >= 0) {
	print " <variablelist>\n";
	foreach $parameter (@{$args{'parameterlist'}}) {
	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
	    print "   <listitem>\n    <para>\n";
	    $lineprefix="     ";
	    output_highlight($args{'parameterdescs'}{$parameter});
	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
	}
	print " </variablelist>\n";
    } else {
	print " <para>\n  None\n </para>\n";
    }
    print "</refsect1>\n";

    output_section_sgml(@_);
    print "</refentry>\n\n";
}

# output struct in sgml DocBook
sub output_struct_sgml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $id;

    $id = "API-struct-".$args{'struct'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry>\n";
    print "<refmeta>\n";
    print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <programlisting>\n";
    print $args{'type'}." ".$args{'struct'}." {\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "  $1 $parameter ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
	    print "  $1 $parameter$2;\n";
	} else {
	    print "  ".$type." ".$parameter.";\n";
	}
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print " <refsect1>\n";
    print "  <title>Members</title>\n";

    print "  <variablelist>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
      ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
      print "    <varlistentry>";
      print "      <term>$parameter</term>\n";
      print "      <listitem><para>\n";
      output_highlight($args{'parameterdescs'}{$parameter});
      print "      </para></listitem>\n";
      print "    </varlistentry>\n";
    }
    print "  </variablelist>\n";
    print " </refsect1>\n";

    output_section_sgml(@_);

    print "</refentry>\n\n";
}

# output enum in sgml DocBook
sub output_enum_sgml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $id;

    $id = "API-enum-".$args{'enum'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry>\n";
    print "<refmeta>\n";
    print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>enum ".$args{'enum'}."</refname>\n";
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <programlisting>\n";
    print "enum ".$args{'enum'}." {\n";
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
        print "  $parameter";
        if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
        }
	print "\n";
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print "<refsect1>\n";
    print " <title>Constants</title>\n";    
    print "  <variablelist>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
      print "    <varlistentry>";
      print "      <term>$parameter</term>\n";
      print "      <listitem><para>\n";
      output_highlight($args{'parameterdescs'}{$parameter});
      print "      </para></listitem>\n";
      print "    </varlistentry>\n";
    }
    print "  </variablelist>\n";
    print "</refsect1>\n";

    output_section_sgml(@_);

    print "</refentry>\n\n";
}

# output typedef in sgml DocBook
sub output_typedef_sgml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $id;

    $id = "API-typedef-".$args{'typedef'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry>\n";
    print "<refmeta>\n";
    print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>typedef ".$args{'typedef'}."</refname>\n";
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
    print "</refsynopsisdiv>\n";

    output_section_sgml(@_);

    print "</refentry>\n\n";
}

# output in sgml DocBook
sub output_intro_sgml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    my $id = $args{'module'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
	print "<refsect1>\n <title>$section</title>\n <para>\n";
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><para>\n";
	}
	output_highlight($args{'sections'}{$section});
	if ($section =~ m/EXAMPLE/i) {
	    print "</para></example>\n";
	}
	print " </para>\n</refsect1>\n";
    }

    print "\n\n";
}

# output in sgml DocBook
sub output_function_gnome {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $id;

    $id = $args{'module'}."-".$args{'function'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<sect2>\n";
    print " <title id=\"$id\">".$args{'function'}."</title>\n";

    print "  <funcsynopsis>\n";
    print "   <funcdef>".$args{'functiontype'}." ";
    print "<function>".$args{'function'}." ";
    print "</function></funcdef>\n";

    $count = 0;
    if ($#{$args{'parameterlist'}} >= 0) {
	foreach $parameter (@{$args{'parameterlist'}}) {
	    $type = $args{'parametertypes'}{$parameter};
	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
		# pointer-to-function
		print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
		print "     <funcparams>$2</funcparams></paramdef>\n";
	    } else {
		print "   <paramdef>".$type;
		print " <parameter>$parameter</parameter></paramdef>\n";
	    }
	}
    } else {
	print "  <void>\n";
    }
    print "  </funcsynopsis>\n";
    if ($#{$args{'parameterlist'}} >= 0) {
	print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
	print "<tgroup cols=\"2\">\n";
	print "<colspec colwidth=\"2*\">\n";
	print "<colspec colwidth=\"8*\">\n";
	print "<tbody>\n";
	foreach $parameter (@{$args{'parameterlist'}}) {
	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
	    print "   <entry>\n";
	    $lineprefix="     ";
	    output_highlight($args{'parameterdescs'}{$parameter});
	    print "    </entry></row>\n";
	}
	print " </tbody></tgroup></informaltable>\n";
    } else {
	print " <para>\n  None\n </para>\n";
    }

    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
	print "<simplesect>\n <title>$section</title>\n";
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><programlisting>\n";
	} else {
	}
	print "<para>\n";
	output_highlight($args{'sections'}{$section});
	print "</para>\n";
	if ($section =~ m/EXAMPLE/i) {
	    print "</programlisting></example>\n";
	} else {
	}
	print " </simplesect>\n";
    }

    print "</sect2>\n\n";
}

##
# output function in man
sub output_function_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'module'}\" 9 \"$args{'function'}\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
    print $args{'function'}." \\- ".$args{'purpose'}."\n";

    print ".SH SYNOPSIS\n";
    print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
    $count = 0;
    my $parenth = "(";
    my $post = ",";
    foreach my $parameter (@{$args{'parameterlist'}}) {
	if ($count == $#{$args{'parameterlist'}}) {
	    $post = ");";
	}
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
	} else {
	    $type =~ s/([^\*])$/$1 /;
	    print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
	}
	$count++;
	$parenth = "";
    }

    print ".SH Arguments\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print ".IP \"".$parameter."\" 12\n";
	output_highlight($args{'parameterdescs'}{$parameter});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output enum in man
sub output_enum_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
    print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";

    print ".SH SYNOPSIS\n";
    print "enum ".$args{'enum'}." {\n";
    $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
        print ".br\n.BI \"    $parameter\"\n";
	if ($count == $#{$args{'parameterlist'}}) {
	    print "\n};\n";
	    last;
	}
	else {
	    print ", \n.br\n";
	}
	$count++;
    }

    print ".SH Constants\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print ".IP \"".$parameter."\" 12\n";
	output_highlight($args{'parameterdescs'}{$parameter});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output struct in man
sub output_struct_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
    print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";

    print ".SH SYNOPSIS\n";
    print $args{'type'}." ".$args{'struct'}." {\n";

    foreach my $parameter (@{$args{'parameterlist'}}) {
        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
	print "\n.br\n";
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
	    print ".BI \"    ".$1."\" ".$parameter.$2." \""."\"\n;\n";
	} else {
	    $type =~ s/([^\*])$/$1 /;
	    print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
	}
	print "\n.br\n";
    }
    print "};\n.br\n";

    print ".SH Arguments\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
	print ".IP \"".$parameter."\" 12\n";
	output_highlight($args{'parameterdescs'}{$parameter});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output typedef in man
sub output_typedef_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
    print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";

    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

sub output_intro_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output in text
sub output_function_text(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    print "Function:\n\n";
    my $start=$args{'functiontype'}." ".$args{'function'}." (";
    print $start;
    my $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print $1.$parameter.") (".$2;
	} else {
	    print $type." ".$parameter;
	}
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",\n";
	    print " " x length($start);
	} else {
	    print ");\n\n";
	}
    }

    print "Arguments:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n";
    }
    output_section_text(@_);
}

#output sections in text
sub output_section_text(%) {
    my %args = %{$_[0]};
    my $section;

    print "\n";
    foreach $section (@{$args{'sectionlist'}}) {
	print "$section:\n\n";
	output_highlight($args{'sections'}{$section});
    }  
    print "\n\n";
}

# output enum in text
sub output_enum_text(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
    print "Enum:\n\n";

    print "enum ".$args{'enum'}." {\n";
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
        print "\t$parameter";
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
	}
	print "\n";
    }
    print "};\n\n";

    print "Constants:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "$parameter\n\t";
	print $args{'parameterdescs'}{$parameter}."\n";
    }

    output_section_text(@_);
}

# output typedef in text
sub output_typedef_text(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
    print "Typedef:\n\n";

    print "typedef ".$args{'typedef'}."\n";
    output_section_text(@_);
}

# output struct as text
sub output_struct_text(%) {
    my %args = %{$_[0]};
    my ($parameter);

    print $args{'type'}." ".$args{'struct'}.":\n\n";
    print $args{'type'}." ".$args{'struct'}." {\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function