Don't apply "smart indent" to parent symbols (#41)

Author: mportiz08

src/components/DocumentationTopic.vue

@@ -235,6 +235,10 @@ export default {
       type: Array,
       required: false,
     },
+    symbolKind: {
+      type: String,
+      required: false,
+    },
     variants: {
       type: Array,
       default: () => ([]),
@@ -255,6 +259,7 @@ export default {
       identifier: this.identifier,
       languages: new Set(Object.keys(this.languagePaths)),
       interfaceLanguage: this.interfaceLanguage,
+      symbolKind: this.symbolKind,
     };
   },
   data() {

src/components/DocumentationTopic/PrimaryContent/DeclarationGroup.vue

@@ -19,8 +19,8 @@
     </p>
     <Source
       :tokens="declaration.tokens"
-      :simple-indent="isSwift && !isCocoaApi"
-      :smart-indent="isCocoaApi"
+      :simple-indent="shouldSimpleIndent"
+      :smart-indent="shouldSmartIndent"
       :language="interfaceLanguage"
     />
   </div>
@@ -30,6 +30,7 @@
 import DeclarationSource from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationSource.vue';
 import Language from 'docc-render/constants/Language';
 import { APIChangesMultipleLines } from 'docc-render/mixins/apiChangesHelpers';
+import { isParentSymbolKind } from 'docc-render/utils/symbols';
 
 /**
  * Renders a code source with an optional caption.
@@ -47,6 +48,9 @@ export default {
     interfaceLanguage: {
       default: () => Language.swift.key.api,
     },
+    symbolKind: {
+      default: () => undefined,
+    },
   },
   props: {
     declaration: {
@@ -79,7 +83,9 @@ export default {
       return this.declaration.platforms.join(', ');
     },
     isSwift: ({ interfaceLanguage }) => interfaceLanguage === Language.swift.key.api,
-    isCocoaApi: ({ languages }) => languages.has(Language.objectiveC.key.api),
+    shouldSimpleIndent: ({ isSwift, shouldSmartIndent }) => isSwift && !shouldSmartIndent,
+    shouldSmartIndent: ({ languages, symbolKind }) => languages.has(Language.objectiveC.key.api)
+      && !isParentSymbolKind(symbolKind),
   },
 };
 </script>

src/constants/SymbolKind.js

@@ -0,0 +1,20 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+// Note: this is not an exhaustive/complete definition of all the various kinds
+// that may be emitted by DocC in Render JSON at the moment—only the ones that
+// the renderer cares about for the time being.
+export default {
+  class: 'class',
+  enum: 'enum',
+  protocol: 'protocol',
+  struct: 'struct',
+  uid: 'uid',
+};

src/utils/symbols.js

@@ -0,0 +1,31 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+import SymbolKind from 'docc-render/constants/SymbolKind';
+
+// Returns whether or not the given symbol kind can be considered a potential
+// "parent" of other symbols.
+//
+// Classes, enums, protocols, and structs can be thought of as parent symbols
+// that may contain child symbol members for any of its
+// properties/functions/initializers/etc for example.
+//
+// eslint-disable-next-line import/prefer-default-export
+export function isParentSymbolKind(kind) {
+  switch (kind) {
+  case SymbolKind.class:
+  case SymbolKind.enum:
+  case SymbolKind.protocol:
+  case SymbolKind.struct:
+  case SymbolKind.uid:
+    return true;
+  default:
+    return false;
+  }
+}

src/views/DocumentationTopic.vue

@@ -89,6 +89,7 @@ export default {
           platforms,
           required: isRequirement,
           roleHeading,
+          symbolKind,
           title = '',
           tags = [],
         } = {},
@@ -122,6 +123,7 @@ export default {
         title,
         topicSections,
         seeAlsoSections,
+        symbolKind,
         variantOverrides,
         variants,
         extendsTechnology,

tests/unit/components/DocumentationTopic.spec.js

@@ -120,6 +120,7 @@ const propsData = {
   ],
   references: {},
   roleHeading: 'Thing',
+  symbolKind: 'thing',
   title: 'FooKit',
   variants: [
     {
@@ -176,6 +177,11 @@ describe('DocumentationTopic', () => {
     expect(wrapper.vm._provided.interfaceLanguage).toEqual(propsData.interfaceLanguage);
   });
 
+  it('provides the symbol kind', () => {
+    // eslint-disable-next-line no-underscore-dangle
+    expect(wrapper.vm._provided.symbolKind).toEqual(propsData.symbolKind);
+  });
+
   it('renders a root div', () => {
     expect(wrapper.is('div.doc-topic')).toBe(true);
   });

tests/unit/components/DocumentationTopic/PrimaryContent/DeclarationGroup.spec.js

@@ -110,4 +110,30 @@ describe('DeclarationGroup', () => {
 
     expect(wrapper.classes()).toContain(multipleLinesClass);
   });
+
+  it('does not apply a "smart indent" for Objective-C classes/structs/etc', () => {
+    ['class', 'enum', 'protocol', 'struct'].forEach((symbolKind) => {
+      const source = createWrapper({
+        provide: {
+          interfaceLanguage: 'occ',
+          languages: new Set(['occ']),
+          symbolKind,
+        },
+      }).find(DeclarationSource);
+      expect(source.exists()).toBe(true);
+      expect(source.props('smartIndent')).toBe(false);
+    });
+  });
+
+  it('applies a "smart indent" for other Objective-C symbols', () => {
+    const source = createWrapper({
+      provide: {
+        interfaceLanguage: 'occ',
+        languages: new Set(['occ']),
+        symbolKind: 'instm',
+      },
+    }).find(DeclarationSource);
+    expect(source.exists()).toBe(true);
+    expect(source.props('smartIndent')).toBe(true);
+  });
 });

tests/unit/utils/symbols.spec.js

@@ -0,0 +1,45 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 Apple Inc. and the Swift project authors
+ * Licensed under Apache License v2.0 with Runtime Library Exception
+ *
+ * See https://swift.org/LICENSE.txt for license information
+ * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+import { isParentSymbolKind } from 'docc-render/utils/symbols';
+import SymbolKind from 'docc-render/constants/SymbolKind';
+
+describe('isParentSymbolKind', () => {
+  it('returns true for kind "class"', () => {
+    expect(isParentSymbolKind(SymbolKind.class)).toBe(true);
+  });
+
+  it('returns true for kind "enum"', () => {
+    expect(isParentSymbolKind(SymbolKind.enum)).toBe(true);
+  });
+
+  it('returns true for kind "protocol"', () => {
+    expect(isParentSymbolKind(SymbolKind.protocol)).toBe(true);
+  });
+
+  it('returns true for kind "struct"', () => {
+    expect(isParentSymbolKind(SymbolKind.struct)).toBe(true);
+  });
+
+  it('returns true for kind "uid"', () => {
+    expect(isParentSymbolKind(SymbolKind.uid)).toBe(true);
+  });
+
+  it('returns false for other kind values', () => {
+    expect(isParentSymbolKind(SymbolKind.unknown)).toBe(false);
+    expect(isParentSymbolKind('clm')).toBe(false);
+    expect(isParentSymbolKind('instm')).toBe(false);
+    expect(isParentSymbolKind('method')).toBe(false);
+    expect(isParentSymbolKind('initializer')).toBe(false);
+    expect(isParentSymbolKind('func')).toBe(false);
+    expect(isParentSymbolKind('function')).toBe(false);
+    expect(isParentSymbolKind('property')).toBe(false);
+    expect(isParentSymbolKind('')).toBe(false);
+  });
+});