I always end up duplicating text to ensure that the XML documentation and the inspector’s tooltips have descriptions available for fields. For example:
/// <summary>
/// The camera to animate
/// </summary>
[Tooltip("The camera to animate")]
[SerializeField] public Camera cameraToAnimate;
I wondered if it was possible to use the XML comment as inspector tooltips. Apparently, it is not.
Other people wondered the same thing as well:
And some propose modifying the documentation generation tool to detect and extract Unity Tooltip annotations. However, if I am not wrong, XML comments are used in many pieces of software while Unity Tooltips aren’t.
So, I think that, the best thing to do would be for Unity to integrate XML comments into its elements such as tooltips.
Additionally, I am confident that they can find other applications of XML in the editor!
I wouldn’t want this feature. XML comments are awful and always felt like a step in the wrong direction, because XML is not human friendly, despite being human readable.
MD comments would be better.
Another thing to keep in mind is that XML comments and tooltips have different application. Tooltip is not documentation, it is literally a tooltip for the end user.
And in your example, neither tooltip nor comment are necessary, as the name is self-explanatiory.
When you are writing an asset thats going to be used widely, on the asset store for example, tools tips are quite important and when describing members/properties it is exceedingly common for the description to be the same between the tooltip and the comment (or at least the XML doc is good enough that it is much better than no tooltip).
Sure the example was contrived but it doesn’t take much to extraplotate it to a real example:
[Tooltip("The camera used to animate the cutscene. If this is null the camera returned by Camera.main will be used.")]
The tooltip might not ALWAYS be the same as the XML Doc but it very often is. I agree that it shouldn’t be a default, but it would be super handy if you could do something like:
[TooltipFromComment]
I imagine the implementation might be a bit messy as the compiler doesn’t parse comments, you would need a separate step to parse comments and popualte some kind of tooltip lookup table. It’s not difficult per se, but it wouldn’t fit the standard patterns so might be a bit of challenge to justify the effort and ongoing maintenance.
In short I think this be great but I don’t think it liekly to happen.
PS XML Comments might be awful, and mostly only used as they are the standard, but this feature could apply regardless of comment format (with a little smarts about deciding which comment applies).
I would disagree as well. They are different uses. xml docs are used for documenting the code. Tooltips are providing tips and help in the inspector (often for folks who are not coders, but designers or other roles who don’t touch code). I wouldn’t want or need to see code docs in the inspector, they are typically related to methods and classes which don’t apply working the editor (apart from visual scripting, but that is a different thing). And tool tips can be for things unrelated to the code. I think it makes sense to keep them seperate (or at least not automatic).
Though if you believe that others would like this feature as well… there might be Asset Store opportunity there.
It’s kind of pointless to mention methods and classes given that Tooltip attribue is specfically only for fields shown in the inspector. Such fields often benefit from a tooltip, and in many cases the code comments would serve much better than no tooltip at all.
If it was to happen I do think it should be optional, and its also only of use for a limtied group of people (mainly asset store publishers or creators of large popular libraries). Accordingly I don’t think it will happen, and probably it is not even worth Unity diverting their resources, but it would be super handy for a subset of users.
However, I do not know where I should start… Do you have any idea about what should I check out to understand what should I do to create that functionality?
On code change, you need to be able to read all .cs files and look for appropriate tags in comments. This will involve a bit of file IO and a bit of text manipulation. Use this to put together (probably) a Dictionary<string, string> where the first string identifies the field (probably Namespace + Class + Field name) and the second is the relevant content read out of the comment.
Separately, you’ll also need to know how to make a C# Attribute to decorate fields with.
Also, you’ll need to know how to use Reflection in order to identify fields which have those Attributes on them.
Finally (if I’m not missing anything) you’ll need to write a custom Inspector or similar functionality, which injects tooltips on the identified Inspector items.
There may be a better method than a custom Inspector class, I’ve not played around with that stuff too much.
Actually… you don’t need to pre-create the dictionary of tooltip content for everything. You could just look up the tooltip for the current file on an as-needed basis. Certainly cache them in a dictionary as you go so they can be re-used. I’d just avoid making people pay a loading cost for a feature unless they’re actually using it, at which point it may be fast enough to not be noticable anyway.
Also, the above will work for scripts which are in the project, but it won’t work for stuff in DLLs and so on because the code isn’t there to read. For that I’d add support to save out tooltip content load and save tooltip content to .xml files or similar.
Now I only use [Tooltip] on exposed fields and get tooltip’s in Unity’s Inspector and code documentation inside Visual Studio with the same thing. The [Tooltip] on a field is even “inherited” to simple getter-properties. In case the field uses a XML style comment and the [Tooltip], then Visual Studio displays both.
FYI for anyone in the future, fields exposed to the Inspector with the [Tooltip] attribute now show the tooltip text in Rider IntelliSense! Here’s an example:
That’s cool, but I doubt that it would solve my case. I need to duplicate this information for automatically generating a documentation website, and having the same tooltips in the inspector. I’ll do some testing, and perhaps I’ll raise the issue on the docfx GitHub issues.
This is one of my biggest pet peeves, and I’m really hoping that CoreCLR introduces this additional control that Unity is lacking right now.
I understand there are arguments in this thread stating how we shouldn’t use this feature. Frankly, I think those arguments are too opinionated. I don’t agree that a separation needs to exist, nor do I think that it is prudent to maintain one.
The separation present is a designer to programmer conversation piece, but in general good XML documentation should not explain code, it should explain in broad strokes the intent of what something does and how to use it.
The real debate should ultimately boil down to questions that are debatable, such as “what do we render as a tooltip?” “do we render all parts of the XML? or just some more designer friendly parts?”
These questions I think are very valid. You may only want specific XML markups to render to tooltips, such as using <tooltip> My new tooltip lives here! <tooltip /> instead of extracting straight from summary. This is something that could also be ultimately extended this to use <tooltip> <see=summary> <tooltip /> (you get the idea)
This would just be an example, there are a number of possibly much better ideas to pick from. Theres simply a lot of potential here to make things easier for developers and give them more tools in how to write good, readable, documentation.
Rider has a feature that renders XML documentation nicely as human-friendly documentation by default. Unity can too. Attributes are not the way, as I cannot see a good reason to ever want them over XML comments.
FYI: Intellisense does not pick up Tooltip attribute when used on the backing field of a Property like so:
[field: SerializeField, Tooltip("This does not show with intellisense!")]
public int Health { get; private set; }
As a side note Photon Fusion 2 has the feature that the OP was asking for. They use XML comments and have an attribute called [InlineHelp] which is quite nice. Not exactly a tooltip but it makes the property expandable in the inspector and shows the xml comments. However their implementation requires your MonoBehaviour to inherit from the base Behaviour class so that their custom inspector can do its work.
I agree with the OP. It would be nice if this was a feature, I don’t see any harm in adding this Quality of Life feature as opt in. I might just implement it myself at this point.
