Improve formatting and clarity of HTML Notes

[raamdev]

This is related to #528.

The HTML Notes generated by Comet Cache include information about the cache file and statistical information about how long it took to generate the cache file and load it. These notes contain a lot of information, but they are currently compressed into a format that makes easily retrieving the information you're looking for unnecessarily difficult (e.g., try finding how this cache file was generated—the text that comes after "via"—or try to understand how long it took to load this cache file, vs how long it took to generate it; also note that the Page URL is listed twice here):

<!-- Comet Cache file path: /cache/comet-cache/cache/http/local-wordpress-dev/2016/06/13/testing-full-width-featured-image.html -->
<!-- Comet Cache file built for (http://local.wordpress.dev/2016/06/13/testing-full-width-featured-image/) in 1.34647 seconds, on: Jun 21st, 2016 @ 10:54 pm UTC; via Auto-Cache Engine. -->
<!-- This Comet Cache file will auto-expire (and be rebuilt) on: Jun 28th, 2016 @ 10:54 pm UTC (based on your configured expiration time). -->
<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<!-- Comet Cache fully functional :-) Cache file served for (http://local.wordpress.dev/2016/06/13/testing-full-width-featured-image/) in 0.01436 seconds, on: Jun 21st, 2016 @ 11:00 pm UTC. -->

I propose that we improve this by making the notes more readable. You'll notice I've changed the wording a bit as well, to make certain things more clear, e.g., "This page was loaded via the cache in 0.01436 seconds" is near the top and is more clear than "Cache file served for (http://local.wordpress.dev/.../) in 0.01436 seconds".

<!--

Comet Cache fully functional. :-) 

This page was loaded via the cache in 0.01436 seconds on Jun 21st, 2016 @ 11:00 pm UTC.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 

Cache File Information and Statistics

File path: /cache/comet-cache/cache/http/local-wordpress-dev/2016/06/13/testing-full-width-featured-image.html

Page URL: http://local.wordpress.dev/2016/06/13/testing-full-width-featured-image/

Date generated: Jun 21st, 2016 @ 10:54 pm UTC

Expiration date: Jun 28th, 2016 @ 10:54 pm UTC (based on your configured expiration time)

Time to generate this cache file: 1.34647 seconds

Generated via: Auto-Cache Engine

-->

These are HTML Notes after all, so we can be liberal with whitespace. If a site owner doesn't want the HTML Notes visible or feels that the extra whitespace adds too much to the page size, they can disable the HTML Notes in Comet Cache → Plugin Options → Enable/Disable.

We may also want to consider adding another option to the

[jaswrks]

I propose that we improve this by making the notes more readable.

I agree. I love the example you gave. I imagine it being tabulated like this also.

<!--
Comet Cache fully functional. :-) 
This page was loaded from the cache in 0.01436 seconds.

--- Cache File Information and Statistics ------------------------------------------------

File path:                        /cache/comet-cache/cache/http/local-wordpress-dev/2016/06/13/testing-full-width-featured-image.html
Page URL:                         http://local.wordpress.dev/2016/06/13/testing-full-width-featured-image/
Date generated:                   Jun 21st, 2016 @ 10:54 pm UTC
Expiration date:                  Jun 28th, 2016 @ 10:54 pm UTC (based on your configured expiration time)
Time to generate this cache file: 1.34647 seconds
Generated via:                    Auto-Cache Engine
-->

[raamdev]

Yep, that looks good to me. Except we shouldn't use hyphens anywhere inside the comment—that's a no-no when it comes to multiline HTML comments. It would be better to use = or * or + for that section divider.

[jaswrks]

Copy that.

---

Including the Comet Cache version might be helpful also. Referencing: wpsharks/comet-cache-pro#262

[raamdev]

Including the Comet Cache version might be helpful also

Hmm, I'd only want to do that when the additional debugging notes are enabled. Including the Comet Cache version creates an information leak that could be helpful to a potential attacker.

[jaswrks]

Yup. That's a great point. In the debugging mode sounds like a good idea to me.

It would be nice if WordPress didn't do this either, and we should probably take a closer look at some of our other plugins for that same sort of leakage in the future.

[Presskopp]

If you really (really) want to dive into this, you can read a bit here:
https://core.trac.wordpress.org/ticket/23394
You can jump to
https://core.trac.wordpress.org/ticket/23394#comment:12

[raamdev]

Noting that we should take into consideration #818 here, where the data generated for the HTML Notes might want to be used for something other than outputting as HTML Notes.

[jaswrks]

Next Release Changelog:

• HTML Debug Notes: This version enhances the HTML comments left in the source code. When debug notes are enabled (i.e., HTML comments) they are now broken down into key/value pairs and tabulated for a cleaner display and easier debugging.

  

[renzms]

@raamdev

Confirmed Working! 👍

[raamdev]

Comet Cache v161119 has been released and includes changes from this GitHub Issue. See the v161119 announcement for further details.

---

This issue will now be locked to further updates. If you have something to add related to this GitHub Issue, please open a new GitHub Issue and reference this one (#790).