fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2026-05-16 15:18:08 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: support docblock comments in "enums-to-docbook.pl"

Browse source 
This script only supported parsing inline documentation comments, of the
type "@ENUM_VAL_NAME: description".

Support also docblock comments, of the type:

    typedef enum {
        /**
         * ENUM_VAL_NAME
         *
         * description
         */
         ENUM_VAL_NAME,
         ...
    }

If both styles are used for the same enum value, the docblock takes
precedence since it's probably more detailed.

Without this change, adding a docblock comment was causing an error in
this script, and then the whole build failed completely.

We need to support this because gtkdoc annotations like "(attributes
NM.internal=1)" only work in docblock comments, not in inline comments,
and we want to start using them for the "enumvals expansion" in
documentation.
This commit is contained in:
Íñigo Huguet 2023-08-11 15:49:02 +02:00
parent dedb48d482
commit 5fee7be1d1
1 changed files with 39 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
tools/enums-to-docbook.pl
View file

@ -20,6 +20,7 @@ our $desc;
our $choice;
our @choices;
our $val;
our $in_choice_docblock;
BEGIN {
my $id = shift @ARGV or die "Missing ID";
@ -81,12 +82,13 @@ if (/^\/\*\*$/) {
$desc = '';
$choice = undef;
@choices = ();
$in_choice_docblock = 0;
} elsif (/^ \* (.+):$/) {
# The name
die "Duplicate name '$1': already processing '$name'" if $name;
$name = $1;
} elsif (/^ \* @(\S+):\s+(.*)$/) {
# The enum choice documentation
# The enum choice documentation (inline `@` style)
$choice = $1;
die "Documentation for '$1' already seen" if grep { $_->[0] eq $choice } @choices;
push @choices, [ $choice, $2 ]
@ -109,6 +111,41 @@ if (/^\/\*\*$/) {
} elsif (/^typedef enum/) {
# Start of an enum
$val = -1;
} elsif (/^ \/\*\*$/) {
# The enum choice documentation start (docblock style)
next unless defined $val;
$in_choice_docblock = 1;
$choice = undef;
} elsif (/^ \*\s+([a-zA-Z_]+)(:.*)?$/) {
# The enum choice name, maybe ignoring gtkdoc annotations
next unless $in_choice_docblock;
$choice = $1;
# Overwrite previous data if we have both inline and docblock (rare, but sometimes necessary)
my ($this) = grep { $_->[0] eq $choice } @choices;
if ($this) {
$this->[1] = '';
} else {
push @choices, [ $choice, '' ];
}
} elsif (/^ \*\s+(.+)$/) {
# An enum choice's description line
next unless $in_choice_docblock;
die "Docblock's first line must be the name of the enum value, saw '$&'" unless defined $choice;
my ($this) = grep { $_->[0] eq $choice } @choices;
if ($this->[1]) {
$this->[1] .= " ";
}
$this->[1] .= $1;
} elsif (/^ \*\s*$/) {
# A blank line in the docblock
next unless $in_choice_docblock;
my ($this) = grep { $_->[0] eq $choice } @choices;
$this->[1] .= "\n";
} elsif (/^ \*+\/$/) {
# End of the docblock
$in_choice_docblock = 0;
$choice = undef;
} elsif (/^\s+(\S+)\s+=\s+([^,\s]+)/) {
# A choice with a literal value
next unless @choices;
@ -188,6 +225,7 @@ END
$choice = undef;
$val = undef;
@choices = ();
$in_choice_docblock = 0;
} else {
# Only care about other lines if we're parsing an enum
next unless $val;