Allow [Tooltip] to be used on class/Component

The following text explains why I think allowing [Tooltip] to be used on a class makes Unity a better product.

Background

In order to provide basic documentation on the purpose of a specific Component, I prefer to write this directly in the source code. The basic documentation is intended to help, usually a Game Designer, how to use the Component or what problem it tries to solve. It’s a simple description only and not a replacement for an actual in-depth documentation.

For me, as a programmer, it’s easier to keep this text up-to-date if it’s stored in the source code, rather than having to write it in another place/tool like a Wiki etc. For the reader, it’s also easier, because he/she does not need to leave the editor.

I basically want a [Tooltip] on a class, rather than on a field only. Unfortunately, [Tooltip] can be used only field declarations only.

5011625--490301--upload_2019-9-29_9-16-27.png

To overcome this limitation, I implemented a [Comment] attribute and a custom editor:

[Comment("This is the comment added to the NewBehaviourScript class.")]
class NewBehaviourScript : MonoBehaviour
{
    [Tooltip("This is the tooltip added to the m_Foo field.")]
    [SerializeField] int m_Foo;
}

5011625--490289--upload_2019-9-29_8-54-44.png

The “?” button can be used to toggle the comment. While this works, I would still like to use [Tooltip] and have Unity show the tooltip instead.

Feature Request

Step 1
Allow [Tooltip] to be used on a class as well.

Step 2
Unity should display the tooltip when the user moves the mouse-pointer over the Component header in the Inspector, just like it’s doing with fields already. Here is a mockup of what I’ve in mind:

5011625--490298--upload_2019-9-29_9-12-17.png

[Tooltip("This is the comment added to the NewBehaviourScript class.")]
class NewBehaviourScript : MonoBehaviour
{
    [Tooltip("This is the tooltip added to the m_Foo field.")]
    [SerializeField] int m_Foo;
}

This allows to provide basic information on a class/Component with minimum effort from a programmer and is the easiest way for the user to read, since he/she does not need to leave the editor. It would be a more consistent experience for the user overall.

2 Likes

Personally, I hate the idea of shipping editor-only code with the game. For example, [Tooltip] won’t fly, [HideInInspector] I’d really like to get rid of, and [SerializeField] I eliminated completely due to access modifier principles. Something I would prefer even more is allowing the use of XML documentation as an alternative to [Tooltip]:

/// <summary>
/// A test class.
/// </summary>
public class Foo : MonoBehaviour
{
    /// <summary>
    /// A test field.
    /// </summary>
    public int bar;
}

Like this, we’d write our in-code documentation once and have it available in the editor and IntelliSense.

I think this would be a useful addition.

@Ramobo While I can see why you might not want that code in a final shipped game, I think it is worth pointing out that some people are making assets to sell to other unity users, and having editor-only code becomes a real benefit in that situation.

I don’t think you get it, I’m using assembly definitions:
• I have a Game.Editor assembly which is only included in the editor platform;
• I have a Game.Debug assembly which for now is included all builds, but won’t be once I update to 2019.3, since it added support for the || operator in compilation constraints, making “UNITY_EDITOR || DEVELOPMENT_BUILD” possible. For now, I just wrapped the only script in it in “#if [constraint]”.
• I have a Game assembly, shipped everywhere, which I don’t want to contain traces of editor-only or debug code. Hell, that’s why I have a whole editor script for injecting my debug script into play mode and development builds, since I don’t want even an EditorOnly GameObject in my scenes, which has a script that may or may not exist. Besides, such an object complicates the development build situation.

EDIT: This is the design that packages use, except they don’t mind the attributes I mentioned. I don’t see any reason why an asset store developer wouldn’t do the same thing. If the user’s version is pre-2017.3 and thus doesn’t support assembly definitions, Unity will simply not recognize them as supported assets and leave them alone, not affecting the user. No backwards compatibility issues here.

bump :slight_smile:

Using the TooltipAttribute on a class is no longer causing a compile-error, thank you for adding this!

[Tooltip("This is the comment added to the NewBehaviourScript class.")]
class NewBehaviourScript : MonoBehaviour {}

What’s left to implement is to display the tooltip when hovering over the component title:

PS: I also submitted a feedback item to Microsoft to add it to Visual Studio:
https://developercommunity.visualstudio.com/t/Visual-Studio-Tools-for-Unity:-Show-Uni/10547377