Feedback Add documentation to Addressables API in code

Addressables API documentation (in code) is pretty much non existent, making it difficult to use. For example, "IsValid" shows up in Visual Studio as:



Why is this a problem you ask? It's because the Addressables API isn't self explanatory. Something as simple as "IsValid" actually has a completely different meaning than what I assumed.

Let me walk you through how working with the Addressables API just has been for me...

Assume I have the following code:

Code (CSharp):

1. [SerializeField] UnityEngine.AddressableAssets.AssetReference m_AssetReference;
2.  
3. public void OnLoadSceneButton()
4. {
5.    if (m_AssetReference.IsValid())
6.    {
7.        Debug.Log("m_AssetReference is valid");
8.        UnityEngine.AddressableAssets.Addressables.LoadSceneAsync(m_AssetReference);
9.    }
10.    else
11.    {
12.        Debug.Log("m_AssetReference not valid");
13.    }
14. }
15.  

... and the AssetReference properly assigned:




Yet

m_AssetReference.IsValid()

returns

false

always.

I assumed IsValid would return true if an addressable asset is assigned or false if it's set to "None". So either the API doesn't work or my assumption how it works is wrong. Let's find out.

Oh wait: there is no documentation in code.

Spoiler

Let's fire up google and search for AssetReference.IsValid. First hit that comes up is this one:
https://docs.unity3d.com/Packages/c...yEngine.AddressableAssets.AssetReference.html

IsValid does not exist on this page. I guess it must have been added to a later version. Let's look at the latest package documentation instead. Change @0.7 to @latest:
https://docs.unity3d.com/Packages/c...yEngine.AddressableAssets.AssetReference.html

Great, it shows page is missing!



So let me figure out what Addressables version I'm actually using. Switch back to Unity. Open Window > Package Manager again. Click documentation link:
https://docs.unity3d.com/Packages/com.unity.addressables@1.7/manual/index.html

Searching for AssetReference.IsValid in the Addressables manual. It has 9 hits, trying to find just "AssetReference" in that list and click link. I'm finally there:
https://docs.unity3d.com/Packages/c....AssetReference.html?q=AssetReference.IsValid

What is IsValid() actually doing?

What a great description. The only thing that would top this is "Returns if the AssetReference is valid".

OK that doesn't help

Let's check the documentation further, scrolling the page to the top and to the bottom.

Oh see, there is IsRuntimeKeyValid(), what's it doing?


It can't get any better than this I guess. Is this auto generated? What's the purpose of such documentation?

Let's trial&error whether this is what I'm looking for...

Code (CSharp):

1. if (m_AssetReference.RuntimeKeyIsValid())
2. {
3.     Debug.Log("m_AssetReference is valid");
4.     UnityEngine.AddressableAssets.Addressables.LoadSceneAsync(m_AssetReference);
5. }

Yay, it's what I was looking for!

This is the current workflow with Addressables when there is no code/proper documentation.

Please fix this asap.

 

I agree with this, but for me it wasn't a problem so far because I just look straight at the source code and see what function does what. AssetReference class is small enough to understand it.

However, in my humble opinion several classes in this package (including this one) are written in a brittle manner. One example is how AssetReference.LoadAssetAsync() just blindly over-writes internal AsyncOperationHandle. So if you accidentally call this method two times without calling Release after the first load was finished, the ref count won't decrement properly and your asset will never be unloaded from memory. Ooops.

Such design mistakes are acceptable for high-level application code that's not critical. Not acceptable for a package that Unity recommends everybody to use by default.

 

Concur 100% with all of the above. I was writing some code to take advantage of a no-longer-existing "MoveToResources(Dict<T,T>)" method that came up in the docs I had landed on -- little did I know that I had apparently ended up on an old docs page. Finding the latest version of the docs similarly required manipulating the URL + google to confirm. =|

If the code is "self-documenting" then I'd suggest removing duplicate (and/or out-of-date/incomplete) docs entirely and just linking directly to the source.

I likewise agree, functionally a bit brittle & there are some very unhelpful naming issues; the OP's example of IsValid() is a very good one, and I fell into precisely the same pit, along with a couple of others.

I know that maintaining core infrastructure like this is difficult -- 'trench work' (ie improving dev-UX) on 'boring' infrastructure stuff like this may not be glamorous, may not earn easy internal promotions, and is likely a lot less fun than working on the latest-and-greatest "next thing". That said, it's stuff like that often makes Unity feel unpolished -- my unsolicited advice: internal leadership should be working to align culture towards one that seriously rewards polishing existing things over shipping "shiny" new stuff that has very low actual production value [or that can only be aspirationally maintained].

Ty.

 

Good to hear. Few more thoughts, apologies for "hijacking" the thread but is related things I got tripped up on, if I may!

1) Somewhat tangentially related, and I've encountered/knew but had forgotten: data in private fields on ScriptableObjects apparently survive termination & re-entry of play mode. I had a simple "isLoading" boolean on a ScriptableObject derived class, which also had several AssetReference fields on it. The AssetReference fields no longer had their ref.Asset filled in after Play Mode re-entry, but the boolean 'isLoading' retained its set-at-runtime value; tripped me up for a good hour or two. The issue isn't what happens on ScriptableObject (though that is annoying & seems wrong) -- issue is the seemingly inconsistent behavior that then gives unusual/unexpected results.

If anything, I'd expect the ScriptableObj's private var to not serialize & to not retain its state [for non-serialized vars] at all -- the annoying part is that it seems to behave differently for the Addressable, even if the latter behavior is more logical/what I'd expect from non-serialized primitive vars too.

2) Already mentioned, but 'IsDone' is awful without documentation -- requires checking source to be useful.

3) How about adding a simple 'IsLoaded' boolean.

4) How about typed access to the asset when using Reference<T>? I haven't read through this forum closely, so I'd be surprised if it wasn't asked for already & there may very well be a good reason it can't be added -- but it'd be nice to not have to cast. Unsure if it's doable without some semi-hackery, but is a +1 on my wishlist for sure.

5) Are there are higher-level [runtime] callbacks at all? ie, can I register & listen for load/unload of any/all assets? Briefly skimmed docs + code, didn't see anything but maybe I missed it.

6) IMO perhaps the most useful thing would be to make the repo public on Github -- even if you don't take PRs at all, and it's simply a secondary "archival" repo [but importantly, with history intact even if you need to squash it some]. Doing so would allow developers to look at the commits/history/blame & actually gain an understanding of the "why" behind any given design decision; it won't answer all questions, but it'd sure make life easier and be 'authoritative' in terms of the 'state' of the package. What I mean by 'state' is: it would directly demonstrate & make clear to developers what the "latest" is on the code -- what's been changing, what the 'status' is (ie what 'phase' of development it's in), how recently it's changed, the severity & recency of bugs and fixes, etc...

EDIT TO ADD:
7) It appears RuntimeKeyIsValid() returns TRUE when an AssetReference has a GUID set even if the object that the GUID refers to is not marked as addressable. So it'll return true even if the runtime key isn't actually what I would expect "valid" to be (as in, it isn't going to work so I'd assume that == invalid, heh). =)

 

I have to give this feedback in general. A ton of the Unity Packages have zero code documentation or half the documentation missing. Sometimes a method has a documentation header but the parameters are not documented. Sometimes I've even found typos in the parameter names (and that IS a problem, since the parameter name is not part of the method signature, changing that later is a breaking change. So that should be 100% checked before a release).

Since the online documentation on a lot of packages is lacking to begin with, this lack of in-code documentation makes it really really hard to figure out what's going on. (And the lack of online documentation is sometimes directly linked to this issue since from what I understand it is generated directly from the code).

I think this has been mentioned by a lot of people in the community, but I want to add my voice: Definition of "done" and "release ready" should include "all the documentation is done and proof read by someone who speaks English fluently"

 

I've solved this by adding a simple extension method:

Code (CSharp):

1. public static class AssetReferenceExtensions
2.     {
3.         public static T GetAsset<T>(this AssetReferenceT<T> assetRef) where T : Object
4.         {
5.             return (T)assetRef.Asset;
6.         }
7.     }

 

... and there is still no documentation available in the code.

You want us to use this complex, convoluted API, but at the same time you ignore to expose documentation in code.

 

What's more unbelievable to me is how they managed to screw up AssetReference API. I've tried using it recently with fairly recent version of the package and was astonished how counter-intuitive and clunky the API is. It's so bad it's beyond the point of improvement... I'll be probably writing some Facade or extension methods for it and patiently waiting for Addressables 2.0 where they'd (hopefully) apply some actual planning and thought before designing API...

 

I hear you.

I'm trying to integrate Addressables in an existing older project at the moment and I'm running into many things that I'm either not understanding or are not supported. Having non-existing to bad documentation doesn't make this situation any better.

Very frustrating experience

 

I'll add my vote to this. Having the documentation appear in visual studio when I go to highlight over the method, etc is something that should always be there. Just seems like the professional thing to do. I can't imagine it'd really be all that much work to slap it in there.

I've gotten started with Addressables the past few days. So far it has its ups and downs for me. I do appreciate the profiling and analyzing tools alot, and overall it seems like a nice way to organize your asset bundles.

However, it does at times seem a little convoluted or like things could be simplified or made a little clearer. Still trying to wrap my head around a few things with it. Maybe better/more documentation would help I'm sure.