Search Unity

  1. Unity 2020.1 has been released.
    Dismiss Notice
  2. Good news ✨ We have more Unite Now videos available for you to watch on-demand! Come check them out and ask our experts any questions!
    Dismiss Notice

XML Comments with assembly defintion

Discussion in 'Package Manager' started by 123099, Jun 14, 2019.

  1. 123099

    123099

    Joined:
    Feb 7, 2016
    Posts:
    4
    Hi guys,

    I have set up a few UPM packages that I pull from github. This all works great.
    Each of the packages has an asmdef assembly definition, which compiles the package scripts and places them in the Library/ScriptAssemblies folder.

    I have also added xml comments to all the classes in each of those assemblies, but the only way to see the comments through intellisense is if I put the generated xml comment files directly inside the Library/ScriptAssemblies folder.

    The issue here is that this folder gets wiped by Unity on various occassions, one of which is project startup. In any case, I saw in many places that I should not manually place anything inside the Library folder.

    My question is then how can I include xml comment files with my UPM packages so that I can see comments and documentation in intellisense? Is there a way to make Unity automatically copy these files alongside the compiled dlls?

    Thanks in advance!
     
  2. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    293
    I just posted about the exact same problem. I'll delete my post and just bump yours. Something I'd like to add is that if you add a package locally from disk then all the xml comments do appear just not with packages from a scoped registry.
     
  3. 123099

    123099

    Joined:
    Feb 7, 2016
    Posts:
    4
    Back to the same topic a few months later - is there any progress on this feature?
     
  4. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    108
    Hello, which IDE are you guys working with?
     
  5. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    293
    Visual Studio 2019 for myself. Though I see the same issue in VS Code as well.
     
  6. cassandraL

    cassandraL

    Unity Technologies

    Joined:
    Dec 7, 2017
    Posts:
    108
    Hello,
    I have tested this and it indeed works as expected when the package is directly embedded in the Packages folder of your project or when using a file reference.
    It does not work properly when the package is installed in the project directly from the registry.
    May I suggest to open a bug about it through the Unity Bug Reporter?

    Thank you
     
  7. 123099

    123099

    Joined:
    Feb 7, 2016
    Posts:
    4
    Hi,

    For me it happened in both Visual Studio 2017 and 2019.
    I have just submitted a bug report, referencing this post, a short description and a step by step reproduction.

    The bug reporter said that an error occured the first couple times I tried submitting it.. but it appears that it submitted the bug multiple times (Case 1192759 Case 1192760 Case 1192761).
     
  8. Antti-Tuppurainen

    Antti-Tuppurainen

    Joined:
    Feb 23, 2015
    Posts:
    1
    Hello, I could not find any issues related to this in the issue tracker.

    Has this issue been fixed in some version of Unity?
     
  9. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    293
    I really hope this is fixed. My team would be willing to upgrade to the latest editor version just for this fix.
     
  10. Adrian

    Adrian

    Joined:
    Apr 5, 2008
    Posts:
    482
    The difference is that local packages are considered editable and their source files are included in the generated C# project. Whatever editor you use then indexes these files, including their xml docs.

    On the other hand, for read-only remote packages from an npm repository or from git, Unity compiles them and then only adds the assembly to the project. Because Unity doesn't generate comment xml files when compiling the assemblies, there editors can't display any documentation.

    There are probably performance tradeoffs here. Generating the xml documentation files will slow down compilation to some degree and including all source files from all packages will slow down the editors.

    Still, showing the documentation inline is incredibly helpful and so I hope Unity will start generating xml comments. Especially for remote packages, which don't change often, generating the comment xml files should make little difference.

    There has been no change as of the latest 2020.1.0a16 alpha.
     
  11. Vapid-Linus

    Vapid-Linus

    Joined:
    Aug 6, 2013
    Posts:
    64
  12. maximeb_unity

    maximeb_unity

    Unity Technologies

    Joined:
    Mar 20, 2018
    Posts:
    199
    Thanks for the feedback!

    This is a known issue that we'll look into improving. In the meantime, you could try the following as a workaround: there is a setting "Generate all .csproj files", under External Tools in the Preferences, which could help with this at the cost of "polluting" the solution with all those additional C# projects. This setting should be available in 2019.2 and 2019.3 with any of the VSCode, Rider or Visual Studio IDE package.
     
    JakHussain likes this.
  13. hyagogow

    hyagogow

    Joined:
    Apr 25, 2014
    Posts:
    3
    This does not work for 2019.3
     
  14. UnityMaru

    UnityMaru

    Community Engagement Manager Unity Technologies

    Joined:
    Mar 16, 2016
    Posts:
    603
    Regarding .csproj generation on 2019.3, you need to uncheck and check again "Generate all .csproj files" in Unity preferences for newly created projects.
     
unityunity