@inheritDoc vs @override

[Jay Young]

I saw r1302 for the Library and had a question.  I assumed in the past that since @inheritDoc implied that what was being documented used the same docs as the overridden thing that @override did not include that behavior.  Since @inheritDoc is now deprecated, does the compiler now attribute that behavior to @override?

[Nick Santos]

The compiler has always treated them as equivalent, and will continue
to do so for the foreseeable future.

[Jay Young]

Awesome.  Thanks for the clarification.

[mvn...@gmail.com]

Should the main documentation page be updated to reflect the deprecation of @inheritDoc?

https://developers.google.com/closure/compiler/docs/js-for-compiler

Or, maybe even just remove it and add it as part of a note under the description for @override.

On Tuesday, September 27, 2011 8:59:43 PM UTC-4, Jay Young wrote:

Awesome.  Thanks for the clarification.

[Mike Lippert]

Updating the documentation page would be a really good thing.

 I had no idea that @inheritDoc was deprecated, and seems to have been deprecated for 3 years. I've used it assuming that at some point jsdoc might support it as well. That's unlikely to happen if the tag is deprecated by closure, since closure use would be the only reason for jsdoc to support it.

[Erik Neumann]

Can someone provide more info on this?  I'm using @inheritDoc everywhere now, do I need to change to use @override instead?   How do you know that @inheritDoc is deprecated?  I don't get any compiler errors (I last updated the compiler a couple months ago, Version: v20140625-8-g6442298).

The only relevant info I've found is from the Michael Bolin book (below) is it still correct?

@override and @inheritDoc
When overriding a method, it should have either the @override or the @inheritDoc annotation. The @override annotation should be used when there is additional information to include in the documentation of the method. For example, if the overridden method returns a subclass of the return type specified by the original method, then that should be documented with @override:
/** @return {example.House} */
example.Person.prototype.getDwelling = function() { /* ... */ };
/**
* In this example, RichPerson is a subclass of Person.
 * @return {example.Mansion}
* @override
*/
example.RichPerson.prototype.getDwelling = function() { /* ... */ };
The @override annotation should also be used when the method signature is the same, but the documentation needs to be updated:
/** @return {string} A description of this object. */
Object.prototype.toString = function() { /* ... */ };
/**
* @return {string} The format of the string will be "(x,y)".
* @override
*/
Point.prototype.toString = function() { /* ... */ };
If there is no need to update the documentation for the overridden method, then @inheritDocshould be used without any other annotations. When viewing a method marked with@inheritDoc, you can assume that the contract of the original method applies to the overridden method. Further, the @inheritDoc annotation implies the @override annotation, so there is no need to include both.
Because most subclass methods maintain the contract of the original method (or because programmers are too lazy to clarify the behavior of a subclass), @inheritDoc is used more often than @override, in practice.

Thanks,

--ErikN

--

---
You received this message because you are subscribed to the Google Groups "Closure Compiler Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to closure-compiler-d...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/closure-compiler-discuss/47f56527-2778-405b-9528-4b23bc2ce50c%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Eric Lemoine]

Le 31 août 2014 01:12, "Erik Neumann" <er...@myphysicslab.com> a écrit :
>
> Can someone provide more info on this?  I'm using @inheritDoc everywhere now, do I need to change to use @override instead?   How do you know that @inheritDoc is deprecated?  I don't get any compiler errors (I last updated the compiler a couple months ago, Version: v20140625-8-g6442298).

I'd have the same questions...

[Tyler Breisacher]

See https://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=Comments#Comments

"Deprecated. Use @override instead."

That said, I doubt we'll explicitly *remove* support for @inheritDoc anytime soon so I wouldn't worry about switching with any urgency.

--

---
You received this message because you are subscribed to the Google Groups "Closure Compiler Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to closure-compiler-d...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/closure-compiler-discuss/CAGZ3h-Hmqj5yye4V7WkvhLDRBKbBs%3DX00_QCnD6%3DF9Lu_0RMfg%40mail.gmail.com.

[Nick Santos]

Note that @inheritDoc is deprecated in the google style guide --
google projects are discouraged from using it.

closure-compiler allows many syntaxes that are discouraged in google
projects, and i don't also don't see any urgent reason to switch.

the short history is that inheritDoc is inherited (/ducks) from the
javadoc spec, which does describe a nuanced difference between
@override and @inheritdoc. But in practice, the compiler has never
enforced a difference. And no engineers understood the difference, so
teams would get into long, tedious arguments about team A's inheritDoc
convention vs. team B's inheritDoc convention.

> https://groups.google.com/d/msgid/closure-compiler-discuss/CAH2y4KARBEBP0CLYiXzCG9G14gpbwDrMvjTDV%2B6Rs-C1ykCKUQ%40mail.gmail.com.