Deprecated method does not point to replacement

[olleharstedt]

Steps to reproduce the issue

Expected result

When a method is deprecated, the documentation should contain information about what to use instead, e.g. a @see tag.

Actual result

No such info. https://api.joomla.org/cms-3/classes/JDatabaseDriver.html#method_getInstance

The method is deprecated, but how to know what to use instead?

System information (as much as possible)

Additional comments

[mbabker]

This one is a weird case of picking up a deprecation because the parent class is deprecated.

When JDatabaseDriver was introduced, it was made a subclass of JDatabase to not create as many B/C issues in changing from the old structure of the database API (think Joomla 2.5) to the redesigned structure. So JDatabase is deprecated, and inherently everything in that parent class is too. The docs parser sees the parent element as deprecated and marks children deprecated as well. If you go to the source file, it's not marked deprecated. This should be closed as a won't fix, the source code is correct and the odds of someone (me) finding time to either make the phpDocumentor rendering account for this odd case scenario or rewrite the API docs engine in full (also accounting for this odd case scenario) are slim to none.

[olleharstedt]

So it is not deprecated?

[olleharstedt]

Just close the issue if so.

[mbabker]

The source code says it is not deprecated. Like I said, it is a quirk with the doc parser and the odds of the parser quirk being dealt with are not good.

[olleharstedt]

Is the doc parser here on github?

[ghost]

@olleharstedt you can close your own Issue yourself.

[mbabker]

It's phpDocumentor, the template can be found at https://github.com/joomla/api.joomla.org

[olleharstedt]

Thanks.

[N6REJ]

@olleharstedt if you work on this would you please make the new referenced item a link i.e. "
"

[mbabker]

Trying to make all the class names links requires changing the inline doc blocks in the source code and IMO worsens readability because you have to wrap everything in a special tag and hope it gets processed, i.e. @deprecated 4.0 Use {@link \Joomla\CMS\Filesystem\File} instead (and that bit doesn't always work, actually per phpDocumentor's documentation it was never fully implemented in 2.x; see https://api.joomla.org/cms-3/classes/Joomla.CMS.Factory.html#method_getDate for an example and I'd suggest the doc blocks be updated to remove that annotation as a result). There isn't a "smart" way to tell the parser "every single thing that looks like a class name should be linked somewhere" (think of this as using a plugin for onContentPrepare to find anything in an article's text property that remotely looks like a class name in Joomla's API and convert it to a link to the API docs site). Linking param types and return types is rather easy, and the parser supports that without issue, because those are expected to either be a class object or a scalar value (boolean/string/void/etc.) and it's easy to skip linking if it's a scalar. Also, with Joomla continuing to enforce a hard 150 character line limit, changing these references creates a lot more work with fighting against PHPCS.

/**
 * Class constructor.
 *
 * @param   Input              $input     An optional argument to provide dependency injection for the application's
 *                                        input object.  If the argument is a JInput object that object will become
 *                                        the application's input object, otherwise a default input object is created.
 * @param   Registry           $config    An optional argument to provide dependency injection for the application's
 *                                        config object.  If the argument is a Registry object that object will become
 *                                        the application's config object, otherwise a default config object is created.
 * @param   WebClient          $client    An optional argument to provide dependency injection for the application's
 *                                        client object.  If the argument is a WebClient object that object will become
 *                                        the application's client object, otherwise a default client object is created.
 * @param   ResponseInterface  $response  An optional argument to provide dependency injection for the application's
 *                                        response object.  If the argument is a ResponseInterface object that object
 *                                        will become the application's response object, otherwise a default response
 *                                        object is created.
 */

// Updated, this becomes...

/**
 * Class constructor.
 *
 * @param   Input              $input     An optional argument to provide dependency injection for the application's
 *                                        input object.  If the argument is a {@link \Joomla\Input\Input} object
 *                                        that object will become the application's input object, otherwise a
 *                                        default input object is created.
 * @param   Registry           $config    An optional argument to provide dependency injection for the application's
 *                                        config object.  If the argument is a {@link \Joomla\Registry\Registry} object
 *                                        that object will become the application's config object, otherwise a default
 *                                        config object is created.
 * @param   WebClient          $client    An optional argument to provide dependency injection for the application's
 *                                        client object.  If the argument is a {@link \Joomla\Application\Web\WebClient}
 *                                        object that object will become the application's client object, otherwise a
 *                                        default client object is created.
 * @param   ResponseInterface  $response  An optional argument to provide dependency injection for the application's
 *                                        response object.  If the argument is a
 *                                        {@link \Psr\Http\Message\ResponseInterface} object that object will become
 *                                        the application's response object, otherwise a default response object is created.
 */