kernel-doc (be9264110e4e874622d588a75daf930539fdf6ea) kernel-doc (bb8fd09e2811e2386bb40b9f0d3c7dd6e7961a1e)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3# vim: softtabstop=4
4
5use warnings;
6use strict;
7
8## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##

--- 555 unchanged lines hidden (view full) ---

564}
565
566##
567# output function in man
568sub output_function_man(%) {
569 my %args = %{$_[0]};
570 my ($parameter, $section);
571 my $count;
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3# vim: softtabstop=4
4
5use warnings;
6use strict;
7
8## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##

--- 555 unchanged lines hidden (view full) ---

564}
565
566##
567# output function in man
568sub output_function_man(%) {
569 my %args = %{$_[0]};
570 my ($parameter, $section);
571 my $count;
572 my $func_macro = $args{'func_macro'};
573 my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
572
573 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
574
575 print ".SH NAME\n";
576 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
577
578 print ".SH SYNOPSIS\n";
579 if ($args{'functiontype'} ne "") {

--- 15 unchanged lines hidden (view full) ---

595 } else {
596 $type =~ s/([^\*])$/$1 /;
597 print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
598 }
599 $count++;
600 $parenth = "";
601 }
602
574
575 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
576
577 print ".SH NAME\n";
578 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
579
580 print ".SH SYNOPSIS\n";
581 if ($args{'functiontype'} ne "") {

--- 15 unchanged lines hidden (view full) ---

597 } else {
598 $type =~ s/([^\*])$/$1 /;
599 print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
600 }
601 $count++;
602 $parenth = "";
603 }
604
603 print ".SH ARGUMENTS\n";
605 $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
606 if ($paramcount >= 0) {
607 print ".SH ARGUMENTS\n";
608 }
604 foreach $parameter (@{$args{'parameterlist'}}) {
605 my $parameter_name = $parameter;
606 $parameter_name =~ s/\[.*//;
607
608 print ".IP \"" . $parameter . "\" 12\n";
609 output_highlight($args{'parameterdescs'}{$parameter_name});
610 }
611 foreach $section (@{$args{'sectionlist'}}) {

--- 205 unchanged lines hidden (view full) ---

817}
818
819sub output_function_rst(%) {
820 my %args = %{$_[0]};
821 my ($parameter, $section);
822 my $oldprefix = $lineprefix;
823
824 my $signature = "";
609 foreach $parameter (@{$args{'parameterlist'}}) {
610 my $parameter_name = $parameter;
611 $parameter_name =~ s/\[.*//;
612
613 print ".IP \"" . $parameter . "\" 12\n";
614 output_highlight($args{'parameterdescs'}{$parameter_name});
615 }
616 foreach $section (@{$args{'sectionlist'}}) {

--- 205 unchanged lines hidden (view full) ---

822}
823
824sub output_function_rst(%) {
825 my %args = %{$_[0]};
826 my ($parameter, $section);
827 my $oldprefix = $lineprefix;
828
829 my $signature = "";
825 if ($args{'functiontype'} ne "") {
826 $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
827 } else {
828 $signature = $args{'function'} . " (";
830 my $func_macro = $args{'func_macro'};
831 my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
832
833 if ($func_macro) {
834 $signature = $args{'function'};
835 } else {
836 if ($args{'functiontype'}) {
837 $signature = $args{'functiontype'} . " ";
838 }
839 $signature .= $args{'function'} . " (";
829 }
830
831 my $count = 0;
832 foreach my $parameter (@{$args{'parameterlist'}}) {
833 if ($count ne 0) {
834 $signature .= ", ";
835 }
836 $count++;
837 $type = $args{'parametertypes'}{$parameter};
838
839 if ($type =~ m/$function_pointer/) {
840 # pointer-to-function
841 $signature .= $1 . $parameter . ") (" . $2 . ")";
842 } else {
843 $signature .= $type;
844 }
845 }
846
840 }
841
842 my $count = 0;
843 foreach my $parameter (@{$args{'parameterlist'}}) {
844 if ($count ne 0) {
845 $signature .= ", ";
846 }
847 $count++;
848 $type = $args{'parametertypes'}{$parameter};
849
850 if ($type =~ m/$function_pointer/) {
851 # pointer-to-function
852 $signature .= $1 . $parameter . ") (" . $2 . ")";
853 } else {
854 $signature .= $type;
855 }
856 }
857
847 $signature .= ")";
858 if (!$func_macro) {
859 $signature .= ")";
860 }
848
849 if ($sphinx_major < 3) {
850 if ($args{'typedef'}) {
851 print ".. c:type:: ". $args{'function'} . "\n\n";
852 print_lineno($declaration_start_line);
853 print " **Typedef**: ";
854 $lineprefix = "";
855 output_highlight_rst($args{'purpose'});

--- 27 unchanged lines hidden (view full) ---

883 output_highlight_rst($args{'purpose'});
884 print "\n";
885 }
886
887 #
888 # Put our descriptive text into a container (thus an HTML <div>) to help
889 # set the function prototypes apart.
890 #
861
862 if ($sphinx_major < 3) {
863 if ($args{'typedef'}) {
864 print ".. c:type:: ". $args{'function'} . "\n\n";
865 print_lineno($declaration_start_line);
866 print " **Typedef**: ";
867 $lineprefix = "";
868 output_highlight_rst($args{'purpose'});

--- 27 unchanged lines hidden (view full) ---

896 output_highlight_rst($args{'purpose'});
897 print "\n";
898 }
899
900 #
901 # Put our descriptive text into a container (thus an HTML <div>) to help
902 # set the function prototypes apart.
903 #
891 print ".. container:: kernelindent\n\n";
892 $lineprefix = " ";
904 $lineprefix = " ";
893 print $lineprefix . "**Parameters**\n\n";
905 if ($paramcount >= 0) {
906 print ".. container:: kernelindent\n\n";
907 print $lineprefix . "**Parameters**\n\n";
908 }
894 foreach $parameter (@{$args{'parameterlist'}}) {
895 my $parameter_name = $parameter;
896 $parameter_name =~ s/\[.*//;
897 $type = $args{'parametertypes'}{$parameter};
898
899 if ($type ne "") {
900 print $lineprefix . "``$type``\n";
901 } else {

--- 797 unchanged lines hidden (view full) ---

1699
1700##
1701# takes a function prototype and the name of the current file being
1702# processed and spits out all the details stored in the global
1703# arrays/hashes.
1704sub dump_function($$) {
1705 my $prototype = shift;
1706 my $file = shift;
909 foreach $parameter (@{$args{'parameterlist'}}) {
910 my $parameter_name = $parameter;
911 $parameter_name =~ s/\[.*//;
912 $type = $args{'parametertypes'}{$parameter};
913
914 if ($type ne "") {
915 print $lineprefix . "``$type``\n";
916 } else {

--- 797 unchanged lines hidden (view full) ---

1714
1715##
1716# takes a function prototype and the name of the current file being
1717# processed and spits out all the details stored in the global
1718# arrays/hashes.
1719sub dump_function($$) {
1720 my $prototype = shift;
1721 my $file = shift;
1707 my $noret = 0;
1722 my $func_macro = 0;
1708
1709 print_lineno($new_start_line);
1710
1711 $prototype =~ s/^static +//;
1712 $prototype =~ s/^extern +//;
1713 $prototype =~ s/^asmlinkage +//;
1714 $prototype =~ s/^inline +//;
1715 $prototype =~ s/^__inline__ +//;

--- 48 unchanged lines hidden (view full) ---

1764
1765 if ($define && $prototype =~ m/^()($name)\s+/) {
1766 # This is an object-like macro, it has no return type and no parameter
1767 # list.
1768 # Function-like macros are not allowed to have spaces between
1769 # declaration_name and opening parenthesis (notice the \s+).
1770 $return_type = $1;
1771 $declaration_name = $2;
1723
1724 print_lineno($new_start_line);
1725
1726 $prototype =~ s/^static +//;
1727 $prototype =~ s/^extern +//;
1728 $prototype =~ s/^asmlinkage +//;
1729 $prototype =~ s/^inline +//;
1730 $prototype =~ s/^__inline__ +//;

--- 48 unchanged lines hidden (view full) ---

1779
1780 if ($define && $prototype =~ m/^()($name)\s+/) {
1781 # This is an object-like macro, it has no return type and no parameter
1782 # list.
1783 # Function-like macros are not allowed to have spaces between
1784 # declaration_name and opening parenthesis (notice the \s+).
1785 $return_type = $1;
1786 $declaration_name = $2;
1772 $noret = 1;
1787 $func_macro = 1;
1773 } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
1774 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1775 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1776 $return_type = $1;
1777 $declaration_name = $2;
1778 my $args = $3;
1779
1780 create_parameterlist($args, ',', $file, $declaration_name);

--- 10 unchanged lines hidden (view full) ---

1791 my $prms = join " ", @parameterlist;
1792 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1793
1794 # This check emits a lot of warnings at the moment, because many
1795 # functions don't have a 'Return' doc section. So until the number
1796 # of warnings goes sufficiently down, the check is only performed in
1797 # -Wreturn mode.
1798 # TODO: always perform the check.
1788 } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
1789 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1790 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1791 $return_type = $1;
1792 $declaration_name = $2;
1793 my $args = $3;
1794
1795 create_parameterlist($args, ',', $file, $declaration_name);

--- 10 unchanged lines hidden (view full) ---

1806 my $prms = join " ", @parameterlist;
1807 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1808
1809 # This check emits a lot of warnings at the moment, because many
1810 # functions don't have a 'Return' doc section. So until the number
1811 # of warnings goes sufficiently down, the check is only performed in
1812 # -Wreturn mode.
1813 # TODO: always perform the check.
1799 if ($Wreturn && !$noret) {
1814 if ($Wreturn && !$func_macro) {
1800 check_return_section($file, $declaration_name, $return_type);
1801 }
1802
1803 # The function parser can be called with a typedef parameter.
1804 # Handle it.
1805 if ($return_type =~ /typedef/) {
1806 output_declaration($declaration_name,
1807 'function',
1808 {'function' => $declaration_name,
1809 'typedef' => 1,
1810 'module' => $modulename,
1811 'functiontype' => $return_type,
1812 'parameterlist' => \@parameterlist,
1813 'parameterdescs' => \%parameterdescs,
1814 'parametertypes' => \%parametertypes,
1815 'sectionlist' => \@sectionlist,
1816 'sections' => \%sections,
1815 check_return_section($file, $declaration_name, $return_type);
1816 }
1817
1818 # The function parser can be called with a typedef parameter.
1819 # Handle it.
1820 if ($return_type =~ /typedef/) {
1821 output_declaration($declaration_name,
1822 'function',
1823 {'function' => $declaration_name,
1824 'typedef' => 1,
1825 'module' => $modulename,
1826 'functiontype' => $return_type,
1827 'parameterlist' => \@parameterlist,
1828 'parameterdescs' => \%parameterdescs,
1829 'parametertypes' => \%parametertypes,
1830 'sectionlist' => \@sectionlist,
1831 'sections' => \%sections,
1817 'purpose' => $declaration_purpose
1832 'purpose' => $declaration_purpose,
1833 'func_macro' => $func_macro
1818 });
1819 } else {
1820 output_declaration($declaration_name,
1821 'function',
1822 {'function' => $declaration_name,
1823 'module' => $modulename,
1824 'functiontype' => $return_type,
1825 'parameterlist' => \@parameterlist,
1826 'parameterdescs' => \%parameterdescs,
1827 'parametertypes' => \%parametertypes,
1828 'sectionlist' => \@sectionlist,
1829 'sections' => \%sections,
1834 });
1835 } else {
1836 output_declaration($declaration_name,
1837 'function',
1838 {'function' => $declaration_name,
1839 'module' => $modulename,
1840 'functiontype' => $return_type,
1841 'parameterlist' => \@parameterlist,
1842 'parameterdescs' => \%parameterdescs,
1843 'parametertypes' => \%parametertypes,
1844 'sectionlist' => \@sectionlist,
1845 'sections' => \%sections,
1830 'purpose' => $declaration_purpose
1846 'purpose' => $declaration_purpose,
1847 'func_macro' => $func_macro
1831 });
1832 }
1833}
1834
1835sub reset_state {
1836 $function = "";
1837 %parameterdescs = ();
1838 %parametertypes = ();

--- 705 unchanged lines hidden --- 		1848 });
1849 }
1850}
1851
1852sub reset_state {
1853 $function = "";
1854 %parameterdescs = ();
1855 %parametertypes = ();

--- 705 unchanged lines hidden ---