Problem/Motivation

From #1315886: Clean up API docs for includes directory, files starting with A-C. There are optional parameters that are not documented correctly in the following files:

  • actions.inc
  • ajax.inc
  • archiver.inc
  • authorize.inc
  • bootstrap.inc
  • cache.inc
  • common.inc

Proposed resolution

Clean up the documentation of optional parameters in these files.

Remaining tasks

Postponed for #1326456: Add missing @param in includes A-C, plus other corrections to some docblocks.

Comments

Lars Toomre’s picture

Lars Toomre CreditAttribution: Lars Toomre commented

The patch now in #1333534-1: Further cleanup for documentation in core/includes files starting with A-G contains a number of fixes for '(optional)' formatting issues.

It does not include the missing '(optional)' indicator for those cases where one has to look at the function profile.

Since there appear to be fewer of those cases, I might suggest that we expand this issue for all A-G includes/ files?

My hope is that we can get #1315886: Clean up API docs for includes directory, files starting with A-C and includes/ D-G committed, then #1333534: Further cleanup for documentation in core/includes files starting with A-G and then we can turn to this issue.

xjm’s picture

xjm
she/her
Primary language English
CreditAttribution: xjm commented

I deliberately made the scope and grouping match the sprint. Also, documentation cleanups might not go in right now, because we are over bug count thresholds.

xjm’s picture

xjm
she/her
Primary language English
CreditAttribution: xjm commented
Assigned: xjm » Unassigned
xjm’s picture

xjm
she/her
Primary language English
CreditAttribution: xjm commented
Issue summary: View changes

Updated issue summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes
Status: Postponed » Closed (won't fix)

I'm closing very old coding standards fixup issues. They are being addressed on other issues mostly.