elixir/t/300-doc-comments.t

#!/usr/bin/env perl
# 300-doc-comments.t: Test elixir doc-comment extraction against the files in tree/ .
#
# Copyright (c) 2020 Christopher White.
# Copyright (c) 2020 D3 Engineering, LLC.
# By Christopher White, <cwhite@d3engineering.com>.
#
# Elixir is free software; you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Elixir is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with Elixir.  If not, see <http://www.gnu.org/licenses/>.
#
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# This file uses core Perl modules only.

use autodie;    # note: still need to check system() calls manually

use FindBin '$Bin';
use lib $Bin;

use File::Spec;
use Test::More;

use TestEnvironment;
use TestHelpers;

# ===========================================================================
# Main

# Set up
my $tenv = TestEnvironment->new;
$tenv->build_repo(sibling_abs_path('tree'))->build_db->update_env;

ok_or_die( -d $tenv->lxr_data_dir, 'database dir exists',
    "Database dir @{[$tenv->lxr_data_dir]} not present");

# Spot-check some identifiers

run_produces_ok('doc-comment query (nonexistent)',
    [$tenv->query_py, qw(v5.4 ident SOME_NONEXISTENT_IDENTIFIER_XYZZY_PLUGH C)],
    [
        qr{^Documented in:},
        {doc => { not => qr{/} }},   # No file paths in the doc section
    ],
    MUST_SUCCEED);

run_produces_ok('doc-comment query (existent but not documented)',
    [$tenv->query_py, qw(v5.4 ident gsb_buffer C)],   # in drivers/i2c/i2c-core-acpi.c
    [
        qr{^Documented in:},
        {doc => { not => qr{/} }}
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, function, documented in C file)',
    [$tenv->query_py, qw(v5.4 ident i2c_acpi_get_i2c_resource C)],
    [
        qr{^Documented in:},
        {doc => qr{drivers/i2c/i2c-core-acpi\.c.+\b45\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, function, documented in C file, #102)',
    [$tenv->query_py, qw(v5.4 ident documented_function_XYZZY C)],
    [
        qr{^Documented in:},
        {doc => qr{issue102\.c.+\b6\b}},
    ],
    MUST_SUCCEED);

# Non-functions

run_produces_ok('ident query (existent, enum, documented in H file)',
    [$tenv->query_py, qw(v5.4 ident memblock_flags C)],
    [
        qr{^Documented in:},
        {doc => qr{\bmemblock\.h.+\b28\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, enum, not documented)',
    [$tenv->query_py, qw(v5.4 ident rseq_cpu_id_state C)],  # uapi/linux/rseq.h:16
    [
        qr{^Documented in:},
        {doc => { not => qr{/} }}
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, struct, documented in H file)',
    [$tenv->query_py, qw(v5.4 ident memblock_region C)],
    [
        qr{^Documented in:},
        {doc => qr{\bmemblock\.h.+\b42\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, struct, not documented)',
    [$tenv->query_py, qw(v5.4 ident epoll_event C)],    # eventpoll.h:77
    [
        qr{^Documented in:},
        {doc => { not => qr{/} }}
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, macro, documented in H file)',
    [$tenv->query_py, qw(v5.4 ident for_each_mem_range C)],
    [
        qr{^Documented in:},
        {doc => qr{\bmemblock\.h.+\b148\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, macro, not documented)',
    [$tenv->query_py, qw(v5.4 ident MEMBLOCK_LOW_LIMIT C)], # memblock.h:343
    [
        qr{^Documented in:},
        {doc => { not => qr{/} }}
    ],
    MUST_SUCCEED);

# Specific cases from #134

# Like regmap_update_bits_base()
run_produces_ok('ident query (existent, function, documented in C file, nonstandard doc comment, #134)',
    [$tenv->query_py, qw(v5.4 ident issue134_function1 C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue134\.c.+\b9\b}},
    ],
    MUST_SUCCEED);

# Like wait_for_completion()
run_produces_ok('ident query (existent, function, documented in C file, nonstandard doc comment, #134)',
    [$tenv->query_py, qw(v5.4 ident issue134_function2 C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue134\.c.+\b25\b}},
    ],
    MUST_SUCCEED);

# Like v4l2_fwnode_endpoint_parse()
run_produces_ok('ident query (existent, prototype, documented in C file), #134',
    [$tenv->query_py, qw(v5.4 ident issue134_function3 C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue134\.c.+\b38\b}},
    ],
    MUST_SUCCEED);

# #186
run_produces_ok('No warnings on macro, #186',
    [$tenv->find_doc, File::Spec->catfile($tenv->lxr_repo_dir, 'issue186.c')],
    [ ],
    MUST_SUCCEED);  # warnings appear on stderr, failing the MUST_SUCCEED checks

# #186 counterexamples
run_produces_ok('ident query (existent, documented as function), #186 counterexample',
    [$tenv->query_py, qw(v5.4 ident i186c_fn1 C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue186-counterexamples\.c.+\b5\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, documented as macro), #186 counterexample',
    [$tenv->query_py, qw(v5.4 ident i186c_fn2 C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue186-counterexamples\.c.+\b20\b}},
    ],
    MUST_SUCCEED);

# #188
run_produces_ok('No warnings on indented #define, #188',
    [$tenv->find_doc, File::Spec->catfile($tenv->lxr_repo_dir, 'issue188.c')],
    [ ],
    MUST_SUCCEED);  # warnings appear on stderr, failing the MUST_SUCCEED checks

# #192

# Like request_firmware()
run_produces_ok('ident query (existent, function, documented in C file, type on preceding line, #192)',
    [$tenv->query_py, qw(v5.4 ident issue192a C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue192\.c.+\b5\b}},
    ],
    MUST_SUCCEED);

run_produces_ok('ident query (existent, function, documented in C file, uppercase return type on preceding line, #192)',
    [$tenv->query_py, qw(v5.4 ident issue192b C)],
    [
        qr{^Documented in:},
        {doc => qr{\bissue192\.c.+\b15\b}},
    ],
    MUST_SUCCEED);

#########################################################################

done_testing;