Search Unity

  1. Megacity Metro Demo now available. Download now.
    Dismiss Notice
  2. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

XML Comments not appearing in visual studio

Discussion in 'Package Manager' started by JakHussain, Jun 19, 2019.

  1. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    318
    I'm following Unity's exact set up by hosting my packages in my own scoped registry and using docfx to extract all my xml comments into a documentation site. However, one thing that really annoys me is that when using my package API in visual studio, the IDE will show me all the available overloads for my functions but not display any of the descriptions written in my XML comments.

    The strange thing is that if my package were to be added to the Unity project as a local package from disk instead of from my scoped registry, all the comments appear.

    Are there any workarounds for this?
     
  2. okcompute_unity

    okcompute_unity

    Joined:
    Jan 16, 2017
    Posts:
    756
  3. dlegare-synapse

    dlegare-synapse

    Joined:
    Jan 17, 2018
    Posts:
    54
    I'm running into this same issue, where Visual Studio can "see" doc comments for embedded packages but not for remote packages. From what I can tell, this isn't related to the Visual Studio plugin for Unity. Rather, it has to do with how Unity generates the script assemblies for packages.

    When you are using an embedded package (i.e. a package where the source code is kept directly within your
    Packages
    folder), Unity adds the package's assembly directly to the Visual Studio solution. This allows VS to fully access the source code and extract the XML comments. However, external packages aren't added to the solution as source code.

    Instead, they are built as DLLs and then added as references to the script assemblies in the VS solution. The DLLs don't retain any of the information from the XML comments, so a separate XML file must be generated and stored next to the DLL in order for Visual Studio (or any other tool) to have access to the comments. This separate file is generated with the -doc compiler flag when compiling a C# project.

    In order to fix this issue, Unity would need to generate the doc XML for each package DLL, and then store it alongside the DLLs in
    Library/ScriptAssemblies
    . I should note that I'm currently on Unity 2018.4.5f1, so I'm not sure if this functionality has already been added in a later version or not. I have filed a bug report for this, since it's easy enough to demonstrate in a fresh Unity project :)
     
    Last edited: Aug 28, 2019
  4. JakHussain

    JakHussain

    Joined:
    Oct 20, 2016
    Posts:
    318
    What would be the reason for Unity to intentionally import remote packages differently to local ones? Their own packages like Entities suffer as a result by making it more difficult for users to learn their new APIs.