Enhance the consistency, usability, maintainability, and overall developer experience of the api-docs across all RWS products. (#235)

Make reference to: https://rws-dev.atlassian.net/wiki/spaces/LTApp/pages/930645143/Developer+Documentation+Improvement+Proposal

Author: Impertatore

TradosStudioTemplate/ManagedReference.common.js renamed to RWSTemplate/ManagedReference.common.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 var common = require('./common.js');
 var classCategory = 'class';
 var namespaceCategory = 'ns';
@@ -20,7 +21,6 @@ exports.transform = function (model) {
       case 'namespace':
         model.isNamespace = true;
         if (model.children) groupChildren(model, namespaceCategory);
-        model[getTypePropertyName(model.type)] = true;
         break;
       case 'class':
       case 'interface':
@@ -36,6 +36,10 @@ exports.transform = function (model) {
     }
   }
 
+  if (model.summary && !model.description) {
+    model.description = model.summary.replace(/<.*?>/gi, '').replace(/(\r\n|\n|\r)/gm, ' ').trim();
+  }
+
   return model;
 }
 
@@ -193,12 +197,14 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
   vm.sourceurl = common.getViewSourceHref(vm, null, gitUrlPattern);
 
   // set to null incase mustache looks up
-  vm.summary = vm.summary || null;
-  vm.remarks = vm.remarks || null;
-  vm.conceptual = vm.conceptual || null;
-  vm.syntax = vm.syntax || null;
-  vm.implements = vm.implements || null;
-  vm.example = vm.example || null;
+  vm.summary = vm.summary || "";
+  vm.description = vm.description || "";
+  vm.remarks = vm.remarks || "";
+  vm.conceptual = vm.conceptual || "";
+  vm.syntax = vm.syntax || "";
+  vm.implements = vm.implements || "";
+  vm.example = vm.example || "";
+  vm.seealso = vm.seealso || [];
   common.processSeeAlso(vm);
 
   // id is used as default template's bookmark
@@ -255,4 +261,9 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
 
     return array;
   }
-}
+  if(vm.syntax.typeParameters) {
+    vm.syntax.typeParameters.forEach(item => {
+      item.description = item.description || "";
+    });
+  }
+}

TradosStudioTemplate/ManagedReference.extension.js renamed to RWSTemplate/ManagedReference.extension.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 /**
  * This method will be called at the start of exports.transform in ManagedReference.html.primary.js
@@ -12,4 +13,4 @@ exports.preTransform = function (model) {
  */
 exports.postTransform = function (model) {
   return model;
-}
+}

RWSTemplate/ManagedReference.html.primary.js

@@ -0,0 +1,69 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+var common = require('./ManagedReference.common.js');
+var extension = require('./ManagedReference.extension.js');
+var overwrite = require('./ManagedReference.overwrite.js');
+
+exports.transform = function (model) {
+  model.yamlmime = "ManagedReference";
+
+  if (overwrite && overwrite.transform) {
+    return overwrite.transform(model);
+  }
+
+  if (extension && extension.preTransform) {
+    model = extension.preTransform(model);
+  }
+
+  if (common && common.transform) {
+    model = common.transform(model);
+  }
+  if (model.type.toLowerCase() === "enum") {
+    model.isClass = false;
+    model.isEnum = true;
+  }
+  if(model._disableToc === undefined) {
+    model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  }
+  model._disableNextArticle = true;
+
+  if (extension && extension.postTransform) {
+    if (model._splitReference) {
+      model = postTransformMemberPage(model);
+    }
+
+    model = extension.postTransform(model);
+  }
+
+  return model;
+}
+
+exports.getOptions = function (model) {
+  if (overwrite && overwrite.getOptions) {
+    return overwrite.getOptions(model);
+  }
+  var ignoreChildrenBookmarks = model._splitReference && model.type && common.getCategory(model.type) === 'ns';
+
+  return {
+    "bookmarks": common.getBookmarks(model, ignoreChildrenBookmarks)
+  };
+}
+
+function postTransformMemberPage(model) {
+  var type = model.type.toLowerCase();
+  var category = common.getCategory(type);
+  if (category == 'class') {
+      var typePropertyName = common.getTypePropertyName(type);
+      if (typePropertyName) {
+          model[typePropertyName] = true;
+      }
+      if (model.children && model.children.length > 0) {
+          model.isCollection = true;
+          common.groupChildren(model, 'class');
+      } else {
+          model.isItem = true;
+      }
+  }
+  return model;
+}

RWSTemplate/ManagedReference.html.primary.tmpl

@@ -0,0 +1,22 @@
+{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
+{{!master(layout/_master.tmpl)}}
+
+{{#isNamespace}}
+  {{>partials/namespace}}
+{{/isNamespace}}
+
+{{#_splitReference}}
+{{#isClass}}
+  {{>partials/class.memberpage}}
+{{/isClass}}
+{{/_splitReference}}
+{{^_splitReference}}
+{{#isClass}}
+  {{>partials/class}}
+{{/isClass}}
+{{/_splitReference}}
+
+{{#isEnum}}
+  {{>partials/enum}}
+{{/isEnum}}
+{{>partials/customMREFContent}}

RWSTemplate/Redirection.html.primary.tmpl

@@ -0,0 +1,8 @@
+{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
+<!DOCTYPE html>
+<html {{#_lang}}lang="{{_lang}}"{{/_lang}}>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0;URL='{{redirect_url}}'">
+  </head>
+</html>

TradosStudioTemplate/RestApi.common.js renamed to RWSTemplate/RestApi.common.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 var common = require('./common.js');
 
 exports.transform = function (model) {
@@ -80,6 +81,21 @@ exports.transform = function (model) {
             model.children = model.children.filter(function (o) { return o; });
         }
     }
+    model.definitions = [];
+    if (model.tags) {
+        model.tags.forEach(function(tag) {
+            (tag.children || []).forEach(function(child) {
+                (child.parameters || []).forEach(function(parameter) { addComplexTypeMetadata(parameter.schema, model.definitions); });
+                (child.responses || []).forEach(function(response) { addComplexTypeMetadata(response.schema, model.definitions); });
+            });
+        });
+    }
+    if (model.children) {
+        model.children.forEach(function(child) {
+            (child.parameters || []).forEach(function(parameter) { addComplexTypeMetadata(parameter.schema, model.definitions); });
+            (child.responses || []).forEach(function(response) { addComplexTypeMetadata(response.schema, model.definitions); });
+        });
+    }
 
     return model;
 
@@ -256,6 +272,72 @@ exports.transform = function (model) {
         }
         return path;
     }
+
+    function addDefinition(definition, definitions) {
+
+        if (!definition) {
+            return;
+        }
+
+        var xRefName = definition.items && definition.items['x-internal-ref-name']
+            ? definition.items['x-internal-ref-name']
+            : definition['x-internal-ref-name'];
+
+        // Not complex type.
+        if (!xRefName) {
+            return;
+        }
+
+        // Definition already exists return.
+        if (definitions.some(function(d) { return d['x-internal-ref-name'] == xRefName; })) {
+            return;
+        }
+
+        // Create clone to not affect object structure used in original location
+        definition = JSON.parse(JSON.stringify(definition));
+
+        // Unify different object structure to be the same
+
+        // Sometimes properties is under items sometimes not
+        if (definition.items && definition.items.properties) {
+            definition.properties = definition.items.properties;
+        }
+
+        // Sometimes ref-name is under items sometimes not
+        definition['x-internal-ref-name'] = xRefName;
+
+        // Sometimes properties are key/value pairs sometimes not
+        if (definition.properties && !Array.isArray(definition.properties)) {
+            definition.properties = Object.keys(definition.properties).map(function(key) {
+                return {
+                    key: key,
+                    value: definition.properties[key]
+                }
+            });
+        }
+
+        // Add definition to definitions list.
+        definitions.push(definition);
+
+        // Loop through properties that refer to other definitions.
+        (definition.properties || []).forEach(function(property) {
+            addComplexTypeMetadata(property.value, definitions);
+        });
+    }
+
+    function addComplexTypeMetadata(child, definitions) {
+        // Add variations of x-internal-ref-name to support
+        if (child && child['x-internal-ref-name']) {
+            child.cTypeId = child['x-internal-ref-name'].replace(/\./g, '_');
+            child.cType = child['x-internal-ref-name'].replace(/([A-Z])/g, '<wbr>$1');
+        }
+        if (child && child.items && child.items['x-internal-ref-name']) {
+            child.cTypeId = child.items['x-internal-ref-name'].replace(/\./g, '_');
+            child.cType = child.items['x-internal-ref-name'].replace(/([A-Z])/g, '<wbr>$1');
+            child.cTypeIsArray = true;
+        }
+        addDefinition(child, definitions);
+    }
 }
 
 exports.getBookmarks = function (model) {

TradosStudioTemplate/RestApi.extension.js renamed to RWSTemplate/RestApi.extension.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 /**
  * This method will be called at the start of exports.transform in RestApi.html.primary.js
@@ -12,4 +13,4 @@ exports.preTransform = function (model) {
  */
 exports.postTransform = function (model) {
   return model;
-}
+}

TradosStudioTemplate/RestApi.html.primary.js renamed to RWSTemplate/RestApi.html.primary.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 var restApiCommon = require('./RestApi.common.js');
 var extension = require('./RestApi.extension.js')
@@ -11,7 +12,10 @@ exports.transform = function (model) {
   if (restApiCommon && restApiCommon.transform) {
     model = restApiCommon.transform(model);
   }
-  model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  if(model._disableToc === undefined) {
+    model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  }
+  model._disableNextArticle = true;
 
   if (extension && extension.postTransform) {
     model = extension.postTransform(model);
@@ -22,4 +26,4 @@ exports.transform = function (model) {
 
 exports.getOptions = function (model) {
   return { "bookmarks": restApiCommon.getBookmarks(model) };
-}
+}

RWSTemplate/RestApi.html.primary.tmpl

@@ -0,0 +1,3 @@
+{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
+{{!master(layout/_master.tmpl)}}
+{{>partials/rest}}

TradosStudioTemplate/UniversalReference.common.js renamed to RWSTemplate/UniversalReference.common.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 var common = require('./common.js');;
 var classCategory = 'class';
@@ -81,7 +82,7 @@ function handleItem(vm, gitContribute, gitUrlPattern) {
   if (vm.inheritance) {
     normalizeLanguageValuePairs(vm.inheritance).forEach(handleInheritance);
   }
-  
+
   common.processSeeAlso(vm);
 
   // id is used as default template's bookmark

TradosStudioTemplate/UniversalReference.extension.js renamed to RWSTemplate/UniversalReference.extension.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 /**
  * This method will be called at the start of exports.transform in UniversalReference.html.primary.js
@@ -12,4 +13,4 @@ exports.preTransform = function (model) {
  */
 exports.postTransform = function (model) {
   return model;
-}
+}

TradosStudioTemplate/UniversalReference.html.primary.js renamed to RWSTemplate/UniversalReference.html.primary.js

@@ -1,4 +1,5 @@
-// Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
 
 var urefCommon = require('./UniversalReference.common.js');
 var extension = require('./UniversalReference.extension.js');
@@ -12,7 +13,10 @@ exports.transform = function (model) {
     model = urefCommon.transform(model);
   }
 
-  model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  if(model._disableToc === undefined) {
+    model._disableToc = model._disableToc || !model._tocPath || (model._navPath === model._tocPath);
+  }
+  model._disableNextArticle = true;
 
   if (extension && extension.postTransform) {
     model = extension.postTransform(model);
@@ -25,4 +29,4 @@ exports.getOptions = function (model) {
   return {
     "bookmarks": urefCommon.getBookmarks(model)
   };
-}
+}

TradosStudioTemplate/UniversalReference.html.primary.tmpl renamed to RWSTemplate/UniversalReference.html.primary.tmpl

@@ -1,4 +1,4 @@
-{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{!Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license.}}
 {{!master(layout/_master.tmpl)}}
 
 {{#isNamespace}}