CacheableDependencyInterface::getCacheMaxAge does not document \Drupal\Core\Cache\Cache::PERMANENT

@joachim Do we have to add the documentation in the API page?

You do this in the code comment for getCacheMaxAge.

Has this been resolved yet? I can make the change in the code comments for that function. As mentioned it looks like you can return Cache::Permanent to instantiate a non-expiring cache.

@Yujiman85 This documentation issue is open. It is not resolved.

I have added the line to the comments for that function, it just needs to be reviewed to make sure it's clear what's being said.

I like the wording. Check over https://www.drupal.org/docs/develop/standards/api-documentation-and-comm... for format and style. In particular I noticed:

If you use a namespace on a class anywhere in documentation, always make sure it is a fully-qualified namespace (beginning with a backslash).

@cilefen Ah, my mistake. It's provided right in the description. I went ahead and made the change and pushed the commit.

There is also this provision:

Lines containing comments (including docblocks) must wrap as close to 80 characters as possible without going over, with a few exceptions...

Okay, I went ahead read that whole page to make sure I'm adhering to all the relevant rules. I made the change and hopefully this time it's good to go.

Hi, @Yujiman85! Thanks for commits.

I rebased MR's branch in order to make it synced up with 10.0.x. I also found out a little phpcs error but what's being said in documentation looks clear enough to me.

It's just a space left at the end of the line 49, now already removed:

FILE: ...rface-docs/web/core/lib/Drupal/Core/Cache/CacheableDependencyInterface.php
--------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
--------------------------------------------------------------------------------
 49 | ERROR | [x] Whitespace found at end of line
--------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
--------------------------------------------------------------------------------

Time: 32ms; Memory: 8MB

I'll be reviewing

So,

Checking getCacheMaxAge() docblock, has the function and return description with fully qualified namespace.
Also, I rerun phpcs, but found no typos.

@joachim I came up with some alternatives.

1) "An object may be cached indefinitely/permanently by returning ..."
2) "A non-expiring cache may be created by returning ..."
3) "To permanently cache an object, return ..."

Hi,
I'll work and edit that.

Ok,
Now the docblock looks like this:

The maximum age for which this object may be cached.
 
@return int
  The maximum time in seconds that this object may be cached.
  An object may be cached indefinitely/permanently by returning
  \Drupal\Core\Cache\Cache::PERMANENT.

@gquisini I should've clarified about the first one, that's my fault. I meant it to be either indefinitely OR permanently used in that statement instead of both with the slash. Or if the slash works for everybody then so be it.

Change the docblock to:

 @return int
    The maximum time in seconds that this object may be cached.
    An object may be cached permanently by returning
    \Drupal\Core\Cache\Cache::PERMANENT.

Needs review.

Committed and pushed 45ec97a437 to 10.1.x and b8a5da0a68 to 10.0.x and d70f1b040d to 9.5.x. Thanks!

Backported to 9.5.x as a docs improvement

Discussed with @longwave we agreed to backport this 9.4.x
Committed bb633d6 and pushed to 9.4.x. Thanks!