Feedback 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.



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. }

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:

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.

 

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.

 

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

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:



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