Add PHPDoc blocks to remaining undocumented functions - #271
Merged
Merged
Conversation
Add PHPDoc blocks (description, @PARAM, @return, and applicable @global tags) to functions that lacked them, across a codebase that already had substantial partial PHPDoc coverage from prior work (notably the vendored Net_DNS2 library files, which are correctly excluded as third-party code - see Net/ and its dependents). Fully completed in this PR: database.php, flowview.php, flowview_bulkarin.php, flowview_cleanup.php, flowview_devices.php, flowview_drop_raw_tables.php, flowview_filters.php, flowview_process.php, flowview_runner.php, flowview_security.php, flowview_upgrade.php, functions-pre13.php, run_schedule.php. Remaining work (tracked as a follow-up PR): flowview_databases.php, flowview_schedules.php, flow_collector.php, setup.php, and functions.php still have undocumented functions and were not completed in this pass given the scale of this plugin's codebase. No functional changes; documentation only. Validated with php -l.
TheWitness
requested review from
bmfmancini and
xmacan
and
a lite review from Copilot
September 24, 2026 11:55
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved moderate issues and inaccurate PHPDoc contracts remain.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
Open (12)
What changed in this PR
Adds PHPDoc blocks to previously undocumented plugin functions without intended runtime changes.
Changes:
- Documents database, UI, CLI, security, upgrade, and compatibility functions.
- Adds parameter, return, and global annotations.
| File | Description |
|---|---|
run_schedule.php |
Documents schedule CLI functions |
functions-pre13.php |
Documents compatibility shims |
flowview.php |
Documents filter and export functions |
flowview_upgrade.php |
Documents upgrade operations |
flowview_security.php |
Documents listener validation |
flowview_runner.php |
Documents worker and signal functions |
flowview_process.php |
Documents process CLI functions |
flowview_filters.php |
Documents filter management functions |
flowview_drop_raw_tables.php |
Documents CLI functions |
flowview_devices.php |
Documents device management functions |
flowview_cleanup.php |
Documents cleanup CLI functions |
flowview_bulkarin.php |
Documents CLI help functions |
database.php |
Documents database helpers |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Fix export_template(): print the yaml_emit()'d data before exit() (the YAML download branch never printed anything) - genuine functional bug, not just a doc mismatch - Add missing @PARAM variable names in database.php PHPDoc blocks (flowview_db_table_create/column_exists/add_column/affected_rows) - Fix load_session_for_filter() return type (string, not void) - Remove incorrect @global $flow_fieldids tag from edit_device() (only used by export_template()) - Fix @global $nesting_arr description in show_devices() (unused here) - Fix @global $sched_actions description in actions_filters() (used for the confirmation box title) - Fix @global $graph_timespans description in show_filters() (unused here) - Fix @global $config description in flowview_upgrade() (used to locate irr_tables.php) - Fix $oput_text param type (string|null) in reports_log_and_notify() - Fix reports_run() return type (bool|null) - Regenerate locales/po/cacti.pot (source line references only) - Fix .gitignore pattern for compiled .mo files (locales/LC_MESSAGES/, not locales/po/)
xmacan
approved these changes
Sep 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds PHPDoc blocks (description,
@param,@return, and applicable@global/@throwstags) to functions that were missing them across this plugin.Fully documented in this PR
database.phpflowview.phpflowview_bulkarin.phpflowview_cleanup.phpflowview_devices.phpflowview_drop_raw_tables.phpflowview_filters.phpflowview_process.phpflowview_runner.phpflowview_security.phpflowview_upgrade.phpfunctions-pre13.phprun_schedule.phpExcluded (vendored third-party code)
Net/DNS2.phpand its full dependency tree (Net_DNS2 library by Mike Pultz, BSD-licensed) are excluded — that library already ships with its own complete PHPDoc coverage.Remaining work (follow-up PR)
Given the size of this plugin, the following files still have undocumented functions and are tracked for a follow-up PR:
flowview_databases.php,flowview_schedules.php,flow_collector.php,setup.php, andfunctions.php(the largest file, ~93 functions).No functional changes — documentation only. All modified files validated with
php -l.