Xml documentation comments imported into View Variables

.gitignore

@@ -81,3 +81,7 @@ Robust.Docfx/api
 
 # C# Dev Kit cache file
 *.lscache
+
+# ignore compiler-generated xml docs
+Resources/ViewVariables/
+Resources/Server/ViewVariables/

MSBuild/Robust.Properties.targets

@@ -31,6 +31,9 @@
   <!-- serialization generator -->
   <Import Project="Robust.Serialization.Generator.targets" Condition="'$(SkipRobustAnalyzer)' != 'true'" />
 
+  <!-- viewvariable xml doc generation -->  
+  <Import Project="Robust.ViewVariables.targets" Condition="'$(ViewVariables)' == 'true'" />
+
   <!-- Robust API system -->
   <Import Project="Robust.ProjectReferences.targets" />
 

MSBuild/Robust.ViewVariables.targets

@@ -0,0 +1,73 @@
+<!--
+This is the MSBuild file that drives the creation of xml docs for use by View Variables.
+
+Normally this is invoked from `Robust.Properties.targets` when a csproj defines `<ViewVariables>`
+in its `<PropertyGroup>`.
+
+The workflow is:
+
+0. Ensure the XmlDocTool is built before any project that uses this system
+1. Make sure the doc folder exists:
+   - `..\Resources\ViewVariables\` for client and shared code, which is shipped to clients.
+   - `..\Resources\Server\ViewVariables\` for server code, which only the server can see.
+     The server hands these docs to clients that are allowed to VV, on demand.
+2. Get MSBuild to generate the xml doc at the path from step 1.
+3. Run XmlDocTool on the generated doc
+
+Step two avoids using `<DocumentationFile>` due to a weird quirk of how that facility
+works. DocumentationFile always causes two copies of the generated xml file to be
+created, one at the path in DocumentationFile and one next to the DLL. This script
+uses the somewhat arcane facility `<DocFileItem>` to side-step that problem and create
+a single copy of the xml docs in the folder we want.
+
+Project files (.csproj), inside or outside Robust Toolbox, opt in with:
+
+```
+  <PropertyGroup>
+    <ViewVariables>true</ViewVariables>
+  </PropertyGroup>
+```
+
+Projects whose name ends in `.Server` are treated as server-only automatically.
+Override that with `<ViewVariablesServerOnly>true|false</ViewVariablesServerOnly>`.
+
+see also
+github.com/dotnet/msbuild/issues/1559
+-->
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <!-- Robust Toolbox root, found relative to this file so it works from content projects too -->
+    <VVRobustDir>$([MSBuild]::NormalizeDirectory('$(MSBuildThisFileDirectory)', '..'))</VVRobustDir>
+    <!-- Doc generation is only enabled to feed VV, we don't require every public member to be documented -->
+    <NoWarn>$(NoWarn);CS1591;CS1573</NoWarn>
+    <!-- Server code docs must not ship to clients, they go in the server-only resources folder -->
+    <ViewVariablesServerOnly Condition="'$(ViewVariablesServerOnly)' == '' And $(MSBuildProjectName.EndsWith('.Server'))">true</ViewVariablesServerOnly>
+    <VVDocDir Condition="'$(ViewVariablesServerOnly)' == 'true'">..\Resources\Server\ViewVariables\</VVDocDir>
+    <VVDocDir Condition="'$(ViewVariablesServerOnly)' != 'true'">..\Resources\ViewVariables\</VVDocDir>
+    <VVDocPath>$(VVDocDir)$(MSBuildProjectName).xml</VVDocPath>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- Add a reference to XmlDocTool so it always gets built before any project that needs it -->
+    <ProjectReference Include="$(VVRobustDir)Robust.XmlDocTool\Robust.XmlDocTool.csproj">
+      <!-- Don't copy the build artifacts from this project to the referencing project's output folder  -->
+      <Private>false</Private>
+      <!-- Indicate that the referencing project isn't actually meant to reference this project's assembly directly -->
+      <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
+      <!-- Build-time tools run on the host, not the target runtime -->
+      <GlobalPropertiesToRemove>RuntimeIdentifier;RestoreRuntimeIdentifier</GlobalPropertiesToRemove>
+    </ProjectReference>
+  </ItemGroup>
+  <Target Name="GenerateXmlDoc" BeforeTargets="CoreCompile">
+    <!-- Ensure the destination folder for the docs exists -->
+    <MakeDir Directories="$(VVDocDir)"/>
+    <ItemGroup>
+      <!-- Slightly arcane invocation of the MSBuild doc generation facility that bypasses the issue explained above -->
+      <DocFileItem Include="$(VVDocPath)" />
+    </ItemGroup>
+  </Target>
+  <Target Name="TrimXmlDoc" AfterTargets="PostBuildEvent">
+    <!-- Run XmlDocTool on the generated doc file -->
+    <!-- Run the dll through the dotnet host rather than relying on a platform-specific apphost existing -->
+    <Exec Command="&quot;$(DOTNET_HOST_PATH)&quot; &quot;$([MSBuild]::NormalizePath('$(VVRobustDir)', 'bin', 'XmlDocTool', 'Robust.XmlDocTool.dll'))&quot; &quot;$(VVDocPath)&quot;" />
+  </Target>
+</Project>

Resources/Locale/en-US/view-variables.ftl

@@ -11,6 +11,8 @@ view-variable-instance-entity-server-components-search-bar-placeholder = Search
 view-variable-instance-entity-add-window-server-components = Add Component [S]
 view-variable-instance-entity-add-window-client-components = Add Component [C]
 
+view-variables-property-type = Type:
+view-variables-property-documentation = Documentation:
 
 ## SoundSpecifier
 vv-sound-none = None

Resources/Server/README.txt

@@ -0,0 +1,5 @@
+/Resources/Server/
+
+Files in this folder are not shipped to the client, and are thus visible only to the server.
+
+See `RobustClientPackaging.ClientIgnoredResources` for refrence.

Robust.Client/Robust.Client.csproj

@@ -8,6 +8,7 @@
     <NoWarn>NU1701;CA1416</NoWarn>
     <OutputPath>../bin/Client</OutputPath>
     <RobustILLink>true</RobustILLink>
+    <ViewVariables>true</ViewVariables>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="DiscordRichPresence" PrivateAssets="compile" />

Robust.Client/UserInterface/Controls/Collapsible.cs

@@ -115,14 +115,16 @@ public string? Title
             set => Label.Text = value;
         }
 
+        public BoxContainer Box { get; }
+
         public CollapsibleHeading()
         {
             ToggleMode = true;
-            var box = new BoxContainer();
-            AddChild(box);
-            box.AddChild(_chevron);
+            Box = new BoxContainer();
+            AddChild(Box);
+            Box.AddChild(_chevron);
             Label = new Label();
-            box.AddChild(Label);
+            Box.AddChild(Label);
         }
 
         public CollapsibleHeading(string title) : this()

Robust.Client/ViewVariables/ClientViewVariablesManager.DocStrings.cs

@@ -0,0 +1,194 @@
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Robust.Shared.Network;
+using Robust.Shared.Network.Messages;
+using Robust.Shared.ViewVariables;
+
+namespace Robust.Client.ViewVariables
+{
+    internal sealed partial class ClientViewVariablesManager
+    {
+        // The client only ever sees the shared docs, server docs are requested from the server.
+        private ViewVariablesDocStrings? _docStrings = null;
+
+        // DocStrings we already asked the server for. null means the server didn't have one.
+        // Cleared on disconnect because a different server may have different code.
+        private readonly Dictionary<(ViewVariablesDocStringKind, string), string?> _remoteDocStrings = new();
+
+        private readonly Dictionary<uint, TaskCompletionSource<string?[]>> _requestedDocStrings = new();
+
+        public void LoadDocStrings()
+        {
+            _docStrings = new(Sawmill, ViewVariablesDocStrings.SharedRoot);
+            _docStrings.EnsureLoaded(_resManager);
+        }
+
+        public string GetDocStringForType(Type type)
+        {
+            return GetDocStringForType(DocStringKeyForType(type));
+        }
+
+        public string GetDocStringForType(string key)
+        {
+            return GetLocalDocString(ViewVariablesDocStringKind.Type, key);
+        }
+
+        public string GetDocStringForFieldOrProperty(string key)
+        {
+            return GetLocalDocString(ViewVariablesDocStringKind.FieldOrProperty, key);
+        }
+
+        public async Task<string[]> GetDocStringsAsync(ViewVariablesDocStringKind kind, IReadOnlyList<string> keys)
+        {
+            LoadDocStrings();
+
+            var result = new string[keys.Count];
+            var missingKeys = new List<string>();
+            var missingIdx = new List<int>();
+
+            for (var i = 0; i < keys.Count; i++)
+            {
+                var key = keys[i];
+
+                if (_docStrings!.TryGet(kind, key, out var local))
+                {
+                    result[i] = local;
+                }
+                else if (_remoteDocStrings.TryGetValue((kind, key), out var cached))
+                {
+                    result[i] = cached ?? ViewVariablesDocStrings.Missing(key);
+                }
+                else
+                {
+                    missingKeys.Add(key);
+                    missingIdx.Add(i);
+                }
+            }
+
+            if (missingKeys.Count == 0 || !_netManager.IsConnected)
+            {
+                foreach (var i in missingIdx)
+                {
+                    result[i] = ViewVariablesDocStrings.Missing(keys[i]);
+                }
+                return result;
+            }
+
+            for (var start = 0; start < missingKeys.Count; start += MsgViewVariablesReqDocStrings.MaxKeys)
+            {
+                // We may have disconnected while waiting on the previous chunk.
+                if (!_netManager.IsConnected)
+                {
+                    for (var k = start; k < missingKeys.Count; k++)
+                    {
+                        result[missingIdx[k]] = ViewVariablesDocStrings.Missing(missingKeys[k]);
+                    }
+                    break;
+                }
+
+                var count = Math.Min(MsgViewVariablesReqDocStrings.MaxKeys, missingKeys.Count - start);
+                var chunk = missingKeys.GetRange(start, count);
+                var remote = await RequestDocStrings(kind, chunk);
+
+                for (var j = 0; j < chunk.Count; j++)
+                {
+                    // A short answer means we never heard back for this key (e.g. we disconnected and the
+                    // request was finished with an empty array). Don't cache it, or the miss would stick
+                    // around after the cache was cleared and carry over to the next server.
+                    if (j >= remote.Length)
+                    {
+                        result[missingIdx[start + j]] = ViewVariablesDocStrings.Missing(chunk[j]);
+                        continue;
+                    }
+
+                    var docString = remote[j];
+                    _remoteDocStrings[(kind, chunk[j])] = docString;
+                    result[missingIdx[start + j]] = docString ?? ViewVariablesDocStrings.Missing(chunk[j]);
+                }
+            }
+
+            return result;
+        }
+
+        public async void ApplyDocStringsAsync(ViewVariablesDocStringKind kind, IReadOnlyList<(string Key, Action<string> Apply)> targets)
+        {
+            if (targets.Count == 0)
+                return;
+
+            var keys = new string[targets.Count];
+            for (var i = 0; i < targets.Count; i++)
+            {
+                keys[i] = targets[i].Key;
+            }
+
+            string[] docStrings;
+            try
+            {
+                docStrings = await GetDocStringsAsync(kind, keys);
+            }
+            catch (Exception e)
+            {
+                Sawmill.Error($"Failed to get DocStrings: {e}");
+                return;
+            }
+
+            for (var i = 0; i < targets.Count; i++)
+            {
+                targets[i].Apply(docStrings[i]);
+            }
+        }
+
+        public static string DocStringKeyForType(Type type)
+        {
+            return type.AssemblyQualifiedName!.Split(", ")[0];
+        }
+
+        private string GetLocalDocString(ViewVariablesDocStringKind kind, string key)
+        {
+            LoadDocStrings();
+
+            return _docStrings!.TryGet(kind, key, out var docString)
+                ? docString
+                : ViewVariablesDocStrings.Missing(key);
+        }
+
+        private Task<string?[]> RequestDocStrings(ViewVariablesDocStringKind kind, List<string> keys)
+        {
+            var msg = new MsgViewVariablesReqDocStrings
+            {
+                RequestId = _nextReqId++,
+                Kind = kind,
+                Keys = keys,
+            };
+
+            var tcs = new TaskCompletionSource<string?[]>();
+            _requestedDocStrings.Add(msg.RequestId, tcs);
+            _netManager.ClientSendMessage(msg);
+            return tcs.Task;
+        }
+
+        private void _netMessageDocStrings(MsgViewVariablesDocStrings message)
+        {
+            if (!_requestedDocStrings.Remove(message.RequestId, out var tcs))
+            {
+                Sawmill.Error($"Server sent us DocStrings we never asked for, request ID {message.RequestId}.");
+                return;
+            }
+
+            tcs.SetResult(message.DocStrings);
+        }
+
+        private void OnDisconnectDocStrings(object? sender, NetDisconnectedArgs e)
+        {
+            _remoteDocStrings.Clear();
+
+            // Nobody is going to answer these anymore, finish them with empty results.
+            foreach (var tcs in _requestedDocStrings.Values)
+            {
+                tcs.TrySetResult(Array.Empty<string?>());
+            }
+            _requestedDocStrings.Clear();
+        }
+    }
+}

Robust.Client/ViewVariables/ClientViewVariablesManager.cs

@@ -6,6 +6,7 @@
 using Robust.Client.UserInterface.Controls;
 using Robust.Client.UserInterface.CustomControls;
 using Robust.Client.ViewVariables.Instances;
+using Robust.Shared.ContentPack;
 using Robust.Shared.GameObjects;
 using Robust.Shared.IoC;
 using Robust.Shared.Localization;
@@ -25,6 +26,7 @@ internal sealed partial class ClientViewVariablesManager : ViewVariablesManager,
         [Dependency] private IRobustSerializer _robustSerializer = default!;
         [Dependency] private IEntityManager _entityManager = default!;
         [Dependency] private IViewVariableControlFactory _controlFactory = default!;
+        [Dependency] private IResourceManager _resManager = default!;
 
         private uint _nextReqId = 1;
         private readonly Vector2i _defaultWindowSize = (640, 420);
@@ -45,6 +47,9 @@ public override void Initialize()
         {
             base.Initialize();
             InitializeDomains();
+            _netManager.RegisterNetMessage<MsgViewVariablesDocStrings>(_netMessageDocStrings);
+            _netManager.RegisterNetMessage<MsgViewVariablesReqDocStrings>();
+            _netManager.Disconnect += OnDisconnectDocStrings;
             _netManager.RegisterNetMessage<MsgViewVariablesOpenSession>(_netMessageOpenSession);
             _netManager.RegisterNetMessage<MsgViewVariablesRemoteData>(_netMessageRemoteData);
             _netManager.RegisterNetMessage<MsgViewVariablesCloseSession>(_netMessageCloseSession);
@@ -274,6 +279,7 @@ protected override bool TryGetSession(Guid guid, [NotNullWhen(true)] out ICommon
             session = null;
             return false;
         }
+
     }
 
     [Virtual]