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:
[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;
}
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:
[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.