Misleading documentation for buffered.increment.enabled property

• Type: Bug
• Status: Closed
• Resolution: Fixed
• Affects Version/s: 7.0.X, Master
• Fix Version/s: 7.0.0 DXP FP37, 7.0.0 DXP SP7, 7.0.5 CE GA6, 7.0.X, 7.1.0 M1, 7.1.X, Master
• Component/s: Documentation, Portal Configuration
• Labels:
  • ee-ts
  • liferay-digital-enterprise-70-sp7
  • liferay-fixpack-de-37-7010
• Branch Version/s:
  7.0.x
• Backported to Branch:
  Committed
• Story Points: 1
• Fix Priority: 3
• Git Pull Request: https://github.com/shuyangzhou/liferay-portal/pull/5573

Description
There are some very confusing statements in the description for the buffered.increment.enabled portal property. First, it claims that disabling buffered increment logic is not recommended, with no explanation as to why. The truth is that if a user does not want the view counter enabled, then they should disable the buffered increment, as that is the only way to disable the view counter. Secondly the documentation says :

If disabling buffered increment logic is truly desired, set this property to false, but also remove the BufferedIncrementAdvice bean from base-spring.xml, so annotated service methods are not skipped.

This makes no sense. Removing the BufferedIncrementAdvice bean from base-spring.xml will cause the service methods to be run (which, in the default implementation, will effectively cause the view counter/downloads counter to be enabled). However, outside of the BufferedIncrementAdvice, everything in the portal (by default) that reads the buffered.increment.enabled portal property treats it as if it indicates whether the view counter/download counter is enabled. So by doing these two things simultaneously, you're effectively telling the portal "I have the view counter/download counter disabled" when it actually is still enabled.

Compare this with the original documentation written by Shuyang, which explained everything much more clearly:

    # Set this to false to disable buffered increment counter by default, each
    # individual counter can still be enabled by overwriting default setting.
    #
    # Disable means completely skipping invoking the annotated service method.
    # If the intention is to still invoking the service method, but not using
    # the buffered increment logic, this can be achieved by removing
    # BufferedIncrementAdvice wiring from base-spring.xml