Function docstrings are handled such that the 'summary' of the function is whatever comes before the first period. For example with this method:

    def fit(self, X, y=None):
        """Fit data X. This is another part that isn't rendered in the summary."""
        ...

The summary will be Fit data X., and the full docstring will be rendered in the detailed method description, as expected.

Now, deprecated attributes become properties, and properties are functions. What sphinx renders as the deprecated attribute docstring is its summary. So deprecating an attribute with

    @property
    @deprecated("The foo parameter is deprecated. Use bar instead")
    def foo(self):
        return self.bar

will only describe foo with The foo parameter is deprecated., that is, whatever comes before the first period.

This is related to #8113, i.e. fixing #8113 could probably fix this.