{"record":{"id":"2cc69176887fb2a6","repo":"rust-lang/rust","slug":"expected-list-as-second-argument-of-ie","errorCode":null,"errorMessage":"Expected list as second argument of {} (ie '[]')","messagePattern":"Expected list as second argument of (.+?) \\(ie '\\[\\]'\\)","errorType":"validation","errorClass":"InvalidCheck","httpStatus":null,"severity":"error","filePath":"src/etc/htmldocck.py","lineNumber":477,"sourceCode":"def get_nb_matching_elements(cache, c, regexp, stop_at_first):\n    tree = cache.get_tree(c.args[0])\n    pat, sep, attr = c.args[1].partition(\"/@\")\n    if sep:  # attribute\n        tree = cache.get_tree(c.args[0])\n        return check_tree_attr(tree, pat, attr, c.args[2], False)\n    else:  # normalized text\n        pat = c.args[1]\n        if pat.endswith(\"/text()\"):\n            pat = pat[:-7]\n        return check_tree_text(\n            cache.get_tree(c.args[0]), pat, c.args[2], regexp, stop_at_first\n        )\n\n\ndef check_files_in_folder(c, cache, folder, files):\n    files = files.strip()\n    if not files.startswith(\"[\") or not files.endswith(\"]\"):\n        raise InvalidCheck(\n            \"Expected list as second argument of {} (ie '[]')\".format(c.cmd)\n        )\n\n    folder = cache.get_absolute_path(folder)\n\n    # First we create a set of files to check if there are duplicates.\n    files = shlex.split(files[1:-1].replace(\",\", \"\"))\n    files_set = set()\n    for file in files:\n        if file in files_set:\n            raise InvalidCheck(\"Duplicated file `{}` in {}\".format(file, c.cmd))\n        files_set.add(file)\n    folder_set = set([f for f in os.listdir(folder) if f != \".\" and f != \"..\"])\n\n    # Then we remove entries from both sets (we clone `folder_set` so we can iterate it while\n    # removing its elements).\n    for entry in set(folder_set):\n        if entry in files_set:","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/rust-lang/rust/blob/7088e4b63a9516ebfbfe2ab2d999cf01a528ac14/src/etc/htmldocck.py#L459-L495","documentation":"Raised as InvalidCheck by check_files_in_folder() when the second argument (the file list) of a 'files' directive does not start with '[' and end with ']'. The files directive expects a bracketed list literal (e.g. `//@ files: dir [a.html b.html]`) so it can be parsed with shlex after stripping the brackets.","triggerScenarios":"Authoring a `//@ files: <folder> <list>` directive where <list> is not wrapped in square brackets. Reached at htmldocck.py:476-479 after the files-strip at line 475.","commonSituations":"Forgetting the brackets; using parentheses or braces instead; pasting a comma-separated list without brackets; trailing characters after the closing bracket break the endswith(']') check.","solutions":["Wrap the file list in square brackets: `//@ files: mydir [file1.html file2.html]`.","Ensure nothing trails after the closing ']' on that directive line.","Separate entries with spaces (commas are tolerated because they are replaced before shlex)."],"exampleFix":"// before\n//@ files: mydir file1.html file2.html\n\n// after\n//@ files: mydir [file1.html file2.html]","handlingStrategy":"validation","validationCode":"def files_list_well_formed(files_str: str) -> bool:\n    return files_str.strip().startswith(\"[\") and files_str.strip().endswith(\"]\")\n\nif not files_list_well_formed(files_arg):\n    raise SystemExit(f\"files directive list must be wrapped in [...]; got {files_arg!r}\")","typeGuard":"def is_valid_files_list(s: str) -> bool:\n    s = s.strip()\n    return s.startswith(\"[\") and s.endswith(\"]\")","tryCatchPattern":"from srcetc_htmldocck import InvalidCheck\ntry:\n    check_files_in_folder(c, cache, folder, files)\nexcept InvalidCheck as e:\n    if \"Expected list as second argument\" in str(e):\n        logging.error(\"wrap the files list in square brackets: [a.html b.html]\")\n    raise","preventionTips":["Always wrap the files directive's list argument in square brackets.","Lint files directives in a pre-commit hook to enforce the bracket shape.","Keep a documented example of each directive form in the test-authoring guide."],"tags":["htmldocck","rustdoc","files-directive","test-template","syntax"],"backgroundTag":null,"analyzedSha":"7088e4b63a9516ebfbfe2ab2d999cf01a528ac14","analyzedAt":"2026-08-10T14:17:03.603Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}