Search Unity

  1. Unity 6 Preview is now available. To find out what's new, have a look at our Unity 6 Preview blog post.
    Dismiss Notice
  2. Unity is excited to announce that we will be collaborating with TheXPlace for a summer game jam from June 13 - June 19. Learn more.
    Dismiss Notice

Feedback Allow [Tooltip] to be used on class/Component

Discussion in 'Editor & General Support' started by Peter77, Sep 29, 2019.

  1. Peter77

    Peter77

    QA Jesus

    Joined:
    Jun 12, 2013
    Posts:
    6,630
    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.

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

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

    Code (CSharp):
    1. [Comment("This is the comment added to the NewBehaviourScript class.")]
    2. class NewBehaviourScript : MonoBehaviour
    3. {
    4.     [Tooltip("This is the tooltip added to the m_Foo field.")]
    5.     [SerializeField] int m_Foo;
    6. }
    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:

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

    Code (CSharp):
    1. [Tooltip("This is the comment added to the NewBehaviourScript class.")]
    2. class NewBehaviourScript : MonoBehaviour
    3. {
    4.     [Tooltip("This is the tooltip added to the m_Foo field.")]
    5.     [SerializeField] int m_Foo;
    6. }
    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.
     
    Last edited: May 10, 2020
    codestage and brunocoimbra like this.
  2. Ramobo

    Ramobo

    Joined:
    Dec 26, 2018
    Posts:
    212
    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]:
    Code (CSharp):
    1. /// <summary>
    2. /// A test class.
    3. /// </summary>
    4. public class Foo : MonoBehaviour
    5. {
    6.     /// <summary>
    7.     /// A test field.
    8.     /// </summary>
    9.     public int bar;
    10. }
    Like this, we'd write our in-code documentation once and have it available in the editor and IntelliSense.
     
  3. Marscaleb

    Marscaleb

    Joined:
    Jan 7, 2014
    Posts:
    1,037
    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.
     
  4. Ramobo

    Ramobo

    Joined:
    Dec 26, 2018
    Posts:
    212
    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.
     
    Last edited: Oct 5, 2019
  5. Peter77

    Peter77

    QA Jesus

    Joined:
    Jun 12, 2013
    Posts:
    6,630
    bump :)

    Using the TooltipAttribute on a class is no longer causing a compile-error, thank you for adding this!
    Code (CSharp):
    1. [Tooltip("This is the comment added to the NewBehaviourScript class.")]
    2. class NewBehaviourScript : MonoBehaviour {}

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

    upload_2023-12-23_11-23-53.png

    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
     
    Last edited: Dec 23, 2023