Improve Optimization Detective documentation

[westonruter]

This is a follow-up to #1763.

• Update copy in docs.
• Remove @access private from interfaces which are intended to be exposed.
• Flesh out some inline docs.
• Add missing @since tags.
• Remove obsolete todos.

See #1857 for follow-up tasks to further flesh out docs.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 66.64%. Comparing base (1f8265d) to head (3f62502).
Report is 12 commits behind head on trunk.

Additional details and impacted files

@@           Coverage Diff           @@
##            trunk    #1782   +/-   ##
=======================================
  Coverage   66.64%   66.64%           
=======================================
  Files          88       88           
  Lines        7015     7015           
=======================================
  Hits         4675     4675           
  Misses       2340     2340           

Flag	Coverage Δ
multisite	66.64% <ø> (ø)
single	37.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[westonruter]

The TODO here can be removed:

performance/plugins/optimization-detective/storage/data.php

Lines 57 to 68 in d94977f

	* Gets the normalized query vars for the current request.
	*
	* This is used as a cache key for stored URL Metrics.
	*
	* TODO: For non-singular requests, consider adding the post IDs from The Loop to ensure publishing a new post will invalidate the cache.
	*
	* @since 0.1.0
	* @access private
	*
	* @return array<string, mixed> Normalized query vars.
	*/
	function od_get_normalized_query_vars(): array {

This was solved with the implementation of ETag in #1722.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: westonruter <[email protected]>
Co-authored-by: felixarntz <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[felixarntz]

@westonruter Thanks, LGTM!

[felixarntz]

Not opposed to this block for now, but this is so detailed I think it should rather be part of some docs/*.md file. Maybe you can move (most of) it as part of #1857. This is probably relevant for one of the more detailed documentation articles to write, and we wouldn't want to have this much content duplicated between method docs and separate documentation.

[westonruter]

Yeah, as part of #1857 I'd love to have a process that would automatically extract the docs from phpdoc and dump it into the markdown files. That would ensure the documentation is as close to the code as possible (in PHP) while also being accessible for ease of reading (in Markdown).

[felixarntz]

While a code reference like that would be helpful, I think large text chunks like this one here still fit better into a more detailed article, e.g. on how to write an Optimization Detective extension.

We'd probably want to avoid duplicating too much between those "manual" articles and automatically generated code reference as well.