In order to provide basic documentation of a specific Component, I prefer to write this directly in the source code. The 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 there is no need to leave the editor.
I propose that Unity should display the [Tooltip] when moving 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;
}
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.
@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.
