JetBrains / JetBrains/resharper-unity

Open online API documentation for code from packages

Open
#1,485 1 comment 2 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
1.2k
Forks
142
PR merge metrics
No merged PRs in 30d

Description

Unity appears to follow a standard URL scheme for API documentation for their own packages. Rider should navigate to this documentation with F1 help.

If a type or type member is defined in a package, then the API URL is going to be:

```
https://docs.unity3d.com/Packages/{package_name}@{package_version}/api/{namespace}.{type_name}.html#{type_member_name}
```

This is only true for packages that begin `com.unity`.

* `{package_name}` can be discovered by looking at the project name (for packages in the `Packages` folder, or added as `.asmdef` projects). Or by looking at the location of the source file for the declaration. We should be able to get the source location because packages are compiled by Unity, from source with debug information, and added as references. If the package is in `Library/PackageCache/{package_name}@{full_package_version}`, then we can parse out the package name. We might also have this information as part of what we display in the `Packages` node of Unity Explorer.
* `{pacakge_version}` is the major.minor of the full version. E.g. `0.3.1-preview10` will have a version of `0.3`
* `{namespace}` and `{type_name}` are obvious
* `{type_member_name}` is the name of an anchor on the doc page. This is constructed as the fully qualified type member name, i.e. namespace, type, type member, parameter types. Fields have no parameter types. Methods appear to be written as fully qualified, then all punctuation is replaced by `_`, such as parentheses, commas and angle brackets for generics. This can lead to double underscores. Parameter types are fully qualified, and primitive types such as `int` are written as `System.Int32`.

E.g. The API docs for `Unity.Rendering.LODGroupExtensions.LODParams.GetHashCode(LODGroupExtensions.LODParams obj)` in the `com.unity.rendering.hybrid` package are at:

```
https://docs.unity3d.com/Packages/com.unity.rendering.hybrid@0.3/api/Unity.Rendering.LODGroupExtensions.LODParams.html#Unity_Rendering_LODGroupExtensions_LODParams_GetHashCode_Unity_Rendering_LODGroupExtensions_LODParams_
```

Also, `Unity.Rendering.InstancedRenderMeshBatchGroup.AddBatch(FrozenRenderSceneTag, Int32, Int32, NativeArray, NativeArray, Int32, Int32, Boolean, EditorRenderData)`:

```
https://docs.unity3d.com/Packages/com.unity.rendering.hybrid@0.3/api/Unity.Rendering.InstancedRenderMeshBatchGroup.html#Unity_Rendering_InstancedRenderMeshBatchGroup_AddBatch_Unity_Rendering_FrozenRenderSceneTag_System_Int32_System_Int32_NativeArray_ArchetypeChunk__NativeArray_System_Int32__System_Int32_System_Int32_System_Boolean_EditorRenderData_
```

* Some types are not fully qualified. In the example above, `NativeArray` and `ArchetypeChunk` are not fully qualified. Perhaps because they are in a different package? Or namespace?
* Research what happens with type generic methods, and operators such as `==`.
* Research Editor and Tests projects. AFAICT, there is no API documentation for these projects
* It's not a huge issue if the type member name is incorrect, as the main page will be correctly loaded
* Do we need/can we have a fallback if the page isn't found? I'm not sure that there is an online search page for these APIs.

Contributor guide

Open the contributing guide

Research direction

Start with Rider F1 help and the Unity Explorer package/source-location information described in the issue. Research package-name and major.minor-version discovery, API anchor construction, generic methods and operators, and whether Editor or Tests projects have documentation. Done means qualifying com.unity package symbols opens the matching Unity API documentation URL, with a considered fallback for missing pages.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, unity
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.