IWorldNameable → INameable, and the related methods in IWorldNameable and ICommandSender

[Pokechu22]

The first change:

• IWorldNameable → INameable. This has no relation to worlds, and is used for e.g. inventories (IInventory), which don't even have a reference to the world (excluding block entities). More specifically, this applies to:

  • EntityMinecart (likely this inheritance is leftover from the days when there was a single minecart class so that EntityMinecartContainer (chests and hoppers) could be named — however, IWorldNameable didn't exist in 1.5 when this change was done so that's odd)
    • This probably explains issues like MC-41893
  • TileEntityBanner for its (useless) custom name
  • IInteractionObject for inventory titles (this interface is something I'll want to clean up later)
  • IInventory for inventory titles (also to clean up)

  Another name that I thought of might be INamableInventory, but due to banners and some of the other stuff that seems like a bad name to me (plus interface IInventory extends INameableInventory seems like a horrible idea).

  This should also be repackaged into net.minecraft.inventory or net.minecraft.tileentity (or perhaps somewhere else).

That change looks nice and innocuous. Unfortunately, I'd also like to request some cleanup for the methods. This is actually a pain, because of #14 — func_70005_c_ is both IWorldNameable.getName() and ICommandSender.getName()... which means that it's also Entity.getName(). Same deal with the other methods in ICommandSender. (Maybe the _ on the end of the method's SRG id/obf name signifies that, I'm not 100% sure). Oh, and these methods are awful and inconsistent.

Anyways, here are some proposed javadocs which I'd like feedback on (both the source and a formatted version; note that the links in the formatted version do not go anywhere and are just provided to show where valid links will be):

• func_70005_c_: IWorldNameable.getName(), ICommandSender.getName(), Entity.getName():

  Gets the name of this thing.  This method has slightly different behavior depending on the interface (for <a href="https://github.com/ModCoderPack/MCPBot-Issues/issues/14">technical reasons</a> the same method is used for both IWorldNameable and ICommandSender):
  
  <dl>
  <dt>{@link net.minecraft.inventory.INameable#getName() INameable.getName()}</dt>
  <dd>Returns the name of this inventory.  If this {@linkplain net.minecraft.inventory#hasCustomName() has a custom name} then this <em>should</em> be a direct string; otherwise it <em>should</em> be a valid translation string.</dd>
  <dd>However, note that <strong>the translation string may be invalid</strong>, as is the case for {@link net.minecraft.tileentity.TileEntityBanner TileEntityBanner} (always returns nonexistent translation code <code>banner</code> without a custom name), {@link net.minecraft.block.BlockAnvil.Anvil BlockAnvil$Anvil} (always returns <code>anvil</code>), {@link net.minecraft.block.BlockWorkbench.InterfaceCraftingTable BlockWorkbench$InterfaceCraftingTable} (always returns <code>crafting_table</code>), {@link net.minecraft.inventory.InventoryCraftResult InventoryCraftResult} (always returns <code>Result</code>) and the {@link net.minecraft.entity.item.EntityMinecart EntityMinecart} family (uses the entity definition).  This is not an exaustive list.</dd>
  <dd>In general, this method should be safe to use on tile entities that implement IInventory.</dd>
  <dt>{@link net.minecraft.command.ICommandSender#getName() ICommandSender.getName()} and {@link net.minecraft.entity.Entity#getName() Entity.getName()}</dt>
  <dd>Returns a valid, displayable name (which may be localized).  For most entities, this is the translated version of its translation string (obtained via {@link net.minecraft.entity.EntityList#getEntityString EntityList.getEntityString}).</dd>
  <dd>If this entity has a custom name set, this will return that name.</dd>
  <dd>For some entities, this will attempt to translate a nonexistent translation string; see <a href="https://bugs.mojang.com/browse/MC-68446">MC-68446</a>.  For {@linkplain net.minecraft.entity.player.EntityPlayer#getName() players} this returns the player's name.  For {@linkplain net.minecraft.entity.passive.EntityOcelot ocelots} this may return the translation of <code>entity.Cat.name</code> if it is tamed.  For {@linkplain net.minecraft.entity.item.EntityItem#getName() item entities}, this will attempt to return the name of the item in that item entity.  In all cases other than players, the custom name will overrule this.</dd>
  <dd>For non-entity command senders, this will return some arbitrary name, such as "Rcon" or "Server".</dd>
  </dl>
  

  Gets the name of this thing. This method has slightly different behavior depending on the interface (for technical reasons the same method is used for both IWorldNameable and ICommandSender):

  INameable.getName()

  Returns the name of this inventory. If this has a custom name then this should be a direct string; otherwise it should be a valid translation string.

  However, note that the translation string may be invalid, as is the case for TileEntityBanner (always returns nonexistent translation code banner without a custom name), BlockAnvil$Anvil (always returns anvil), BlockWorkbench$InterfaceCraftingTable (always returns crafting_table), InventoryCraftResult (always returns Result) and the EntityMinecart family (uses the entity definition). This is not an exaustive list.

  In general, this method should be safe to use on tile entities that implement IInventory.

  ICommandSender.getName() and Entity.getName()

  Returns a valid, displayable name (which may be localized). For most entities, this is the translated version of its translation string (obtained via EntityList.getEntityString).

  If this entity has a custom name set, this will return that name.

  For some entities, this will attempt to translate a nonexistent translation string; see MC-68446. For players this returns the player's name. For ocelots this may return the translation of entity.Cat.name if it is tamed. For item entities, this will attempt to return the name of the item in that item entity. In all cases other than players, the custom name will overrule this.

  For non-entity command senders, this will return some arbitrary name, such as "Rcon" or "Server".

• func_145818_k_: IWorldNameable.hasCustomName(), Entity.hasCustomName()

  Checks if this thing has a custom name.  This method has slightly different behavior depending on the interface (for <a href="https://github.com/ModCoderPack/MCPBot-Issues/issues/14">technical reasons</a> the same method is used for both IWorldNameable and Entity):
  
  <dl>
  <dt>{@link net.minecraft.inventory.INameable#hasCustomName() INameable.hasCustomName()}</dt>
  <dd>If true, then {@link #getName()} probably returns a preformatted name; otherwise, it probably returns a translation string.  However, exact behavior varies.</dd>
  <dt>{@link net.minecraft.entity.Entity#hasCustomName() Entity.hasCustomName()}</dt>
  <dd>If true, then {@link net.minecraft.entity.Entity#getCustomNameTag() Entity.getCustomNameTag()} will return a non-empty string, which will be used by {@link #getName()}.</dd>
  </dl>
  

  Checks if this thing has a custom name. This method has slightly different behavior depending on the interface (for technical reasons the same method is used for both IWorldNameable and Entity):

  INameable.hasCustomName()

  If true, then getName() probably returns a preformatted name; otherwise, it probably returns a translation string. However, exact behavior varies.

  Entity.hasCustomName()

  If true, then Entity.getCustomNameTag() will return a non-empty string, which will be used by getName().

• func_145748_c_: IWorldNameable.getDisplayName(), ICommandSender.getDisplayName(), Entity.getDisplayName():

  This maybe could use a rename, but I don't know what it should be named — something like getNameComponent.

  Returns a displayable component representing this thing's name.  This method should be implemented slightly differently depending on the interface (for <a href="https://github.com/ModCoderPack/MCPBot-Issues/issues/14">technical reasons</a> the same method is used for both IWorldNameable and ICommandSender), but unlike {@link #getName()} this method will generally behave sanely.
  
  <dl>
  <dt>{@link net.minecraft.inventory.INameable#getDisplayName() INameable.getDisplayName()}</dt>
  <dd>A normal component.  Might be a translation component or a text component depending on the context.  Usually implemented as:</dd>
  <dd><pre><code>return this.{@link net.minecraft.inventory.INameable#hasCustomName() hasCustomName()} ? new TextComponentString(this.{@link #getName()}) : new TextComponentTranslation(this.{@link #getName()});</code></pre></dd>
  <dt>{@link net.minecraft.command.ICommandSender#getDisplayName() ICommandSender.getDisplayName()} and {@link net.minecraft.entity.Entity#getDisplayName() Entity.getDisplayName()}</dt>
  <dd>For most entities, this returns the result of {@link #getName()}, with {@linkplain net.minecraft.scoreboard.ScorePlayerTeam#formatPlayerName scoreboard formatting} and a {@linkplain net.minecraft.entity.Entity#getHoverEvent special hover event}.</dd>
  <dd>For non-entity command senders, this will return the result of {@link #getName()} in a text component.</dd>
  </dl>
  

  Returns a displayable component representing this thing's name. This method should be implemented slightly differently depending on the interface (for technical reasons the same method is used for both IWorldNameable and ICommandSender), but unlike getName this method will generally behave sanely.

  INameable.getDisplayName()

  A normal component. Might be a translation component or a text component depending on the context. Usually implemented as:

  return this.hasCustomName() ? new TextComponentString(this.getName()) : new TextComponentTranslation(this.getName());

  ICommandSender.getDisplayName() and Entity.getDisplayName()

  For most entities, this returns the result of getName(), with scoreboard formatting and a special hover event.

  For non-entity command senders, this will return the result of getName() in a text component.

Note that to find declarations of these methods, it's easiest to use findallm, for instance findallm func_70005_c_ or findallm ^Entity\.func_70005_c_

[kashike]

MinecraftForge/MCPConfig@1934376

[Pokechu22]

I've updated the javadocs for this too.