Search Unity

  1. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

Resolved Is there any way to preserve comments/summaries from code with Assembly Definitions?

Discussion in 'Scripting' started by SomeGuy22, Mar 18, 2023.

  1. SomeGuy22

    SomeGuy22

    Joined:
    Jun 3, 2011
    Posts:
    722
    I've been working on an open-source Package to help with SDK integration and realized when testing it out in another project that all of my summary comments have vanished when viewing the Package's function definitions from the main assembly (regular project scripts). This is a feature within Visual Studio which lets you hover over a type and see developer insight comments next to your mouse cursor. Furthermore, when I use the "peek definition" feature I can see that all comments have been erased.

    As you can probably guess from the title, I think this is the result of utilizing an Assembly Definition within my package. I used it because I've heard that this is the best practice and in fact this is Unity's recommended package workflow. I guess it makes sense why the comments would be erased if the main assembly can only see some form of the "compiled" version. However, for a package like the one I'm trying to create where working with the API can be a little complicated (and the provided SDK has comments of its own that are getting scrubbed away) I'd really love to let users see all the notes I've written to help them use it more efficiently. Also, I can see the source code files themselves in the "project" window so I'm not sure why Visual Studio is unable to just peek into that for the comments, but maybe this is some weird limitation of the system.

    I could try just removing the .asmdef file and letting users just include all of the code into their main assembly, however it would remove one of the benefits of the assembly which is having code that compiles separately from their project. The included SDK is pretty hefty and I don't want users to have that kind of bloat in their project; it would be a compilation performance hit essentially. So is there any way to preserve the speed gains of the assembly file while still allowing users to see comments in my package? Thanks in advance!
     
  2. SomeGuy22

    SomeGuy22

    Joined:
    Jun 3, 2011
    Posts:
    722
    Surprisingly I did find a solution for this thanks to this blog post by Naga Chiang. It turns out it may not be the assembly definition which is erasing the comments (unless it's some combination of this) but the fact that Visual Studio itself hasn't generated a project for codebase that was included in my package. If you enable .csproj for "Git Packages" in Edit->Preferences for your Unity project, the package code will be included in the solution and I do see the summary comments when hovering over my functions! Unfortunately this has to be done on the user side but I can at least I can direct my users to that option if they're looking for more info. Hope that helps anyone coming across this in the future!
     
  3. waltypuddling

    waltypuddling

    Joined:
    Nov 9, 2023
    Posts:
    1
    You share relevant real topics when commenting frequently. I think this is really appropriate. Each function of the tool has a certain role. I'm not sure why Visual Studio can't simply go into the source code files for the comments in the "project" area