Fix comment conversion in actor-cache.h.

[kentonv]

This set of three methods had been grouped together, with a single comment under them applying to all three. d3f25fc broke apart the group and placed the comment so it appears to apply only to the third method.

I'm not sure if there may have been more instances like this around the codebase. I just happened to see this.

[ohodson]

This set of three methods had been grouped together, with a single comment under them applying to all three. d3f25fc broke apart the group and placed the comment so it appears to apply only to the third method.

Perhaps we should go further here, as we are updating it, because clangd does not detect that the comment applies to the three methods here and part of the reasoning for going with a more traditional comment style was to integrate better with IDEs. I've added some tentative suggestions with that in mind.

I did not find which PITR API the original comment was referring to, but that's my bad.

[jasnell]

LGTM with @ohodson's suggestions

[kentonv]

I don't agree with the suggestions: It makes it harder for a human to read the header, adding noise.

The benefit for clangd is not worth it. The worst case is that a human gets no tooltip when hovering over a call and instead has to jump-to-definition. Unlike with the old comment style, clangd will not display the wrong comment as a result of this.

Being able to group declarations and comment on them as one is important to allow humans to quickly understand what they are looking at, without having to read each comment individually.

[jasnell]

I'm not going to block on it. I prefer the suggestions but it's not worth blocking on so I'm good with this landing either way.

[ohodson]

Okay here if you reject the comments.

The methods above this little block in actor-cache.h have helpful comments (much more so than my suggestions), and so do the comments in actor-state.h introduced in https://github.com/cloudflare/workerd/pull/744/files. It might be reasonable to have a pointer to those as an example implementation or a concrete pointer to the API. I don't know, it seems somewhat intuitive, just riffing on options.

[kentonv]

I'm sure the comments could always be better but my intent with this PR was just to fix a regression in the comment understandability that was introduced when the comment style was changed. This bring the comment back to representing exactly the same information as it did before (except with the above-declaration style rather than below-declaration).