New feature proposal: XML documentation as tooltips

I always end up duplicating text to ensure that the XML documentation and the inspector's tooltips have descriptions available for fields. For example:

Code (CSharp):

1.         /// <summary>
2.         /// The camera to animate
3.         /// </summary>
4.         [Tooltip("The camera to animate")]
5.         [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:

• c# - Unity inspector does not display XML docs (<summary>) as tooltip - Stack Overflow
  
• Using C# summary documentation as tooltip in Unity - Game Development Stack Exchange

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!

What do you think?

 

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:

Code (csharp):

1.  
2. [Tooltip("The camera used to animate the cutscene. If this is null the camera returned by Camera.main will be used.")]
3.  

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:

Code (csharp):

1. [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.

 

I would really like to code it and try it out!

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?

 

A few bits and pieces.

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

 

I did the same thing for quite a long time, but then asked Microsoft if they could implement to use the [Tooltip] for intellisense in Visual Studio too and they did:
https://developercommunity.visualst...o-tools-for-unity-use-unityenginetoolt/683906

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.

 

Very nice. Now we just need the Rider team to catch up

 

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:


(Working in Unity 2021.3.24, Rider 2021.3.4)

 

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.