Merge pull request #2827 from quantified-uncertainty/description->doc

Changed @description Tag to @doc
quantified-uncertainty · Dec 30, 2023 · 83776e0 · 83776e0 · vercel · Dec 30, 2023
2 parents 212708a + 4a39998
commit 83776e0
Show file tree

Hide file tree

Showing 10 changed files with 34 additions and 31 deletions.
diff --git a/.changeset/hot-boats-fail.md b/.changeset/hot-boats-fail.md
@@ -0,0 +1,6 @@
+---
+"@quri/squiggle-lang": patch
+"@quri/squiggle-components": patch
+---
+
+Breaking: Changed Tag.description to Tag.doc
diff --git a/packages/components/src/components/SquiggleViewer/utils.ts b/packages/components/src/components/SquiggleViewer/utils.ts
@@ -126,7 +126,7 @@ export function useGetSubvalueByPath() {
 }
 
 export function getValueComment(value: SqValueWithContext): string | undefined {
-  const _value = value.context.docstring() || value.tags.description();
+  const _value = value.context.docstring() || value.tags.doc();
   return _value && _value.length > 0 ? _value : undefined;
 }
 

diff --git a/packages/components/src/stories/SquigglePlayground.stories.tsx b/packages/components/src/stories/SquigglePlayground.stories.tsx
@@ -266,7 +266,7 @@ export const Tagged: Story = {
     defaultCode: `z = 34 -> Tag.format(".1f")
 
     @name("My favorite Dist")
-    @description("This is a long description")
+    @doc("This is a long description")
     @format("$.2")
     x = 5 to 10
     

diff --git a/packages/squiggle-lang/__tests__/SqProject/SqProject_test.ts b/packages/squiggle-lang/__tests__/SqProject/SqProject_test.ts
@@ -46,12 +46,12 @@ test("test decorated exports", async () => {
     export x = 5
 
     @name("Y")
-    @description("whatever")
+    @doc("whatever")
     export y = 6
   `
   );
   expect(await runFetchExports(project, "main")).toBe(
-    '{x: 5, with params name: "X",y: 6, with params name: "Y", description: "whatever"}'
+    '{x: 5, with params name: "X",y: 6, with params name: "Y", doc: "whatever"}'
   );
 });
 

diff --git a/packages/squiggle-lang/__tests__/library/tag_test.ts b/packages/squiggle-lang/__tests__/library/tag_test.ts
@@ -5,17 +5,14 @@ describe("Tags", () => {
     testEvalToBe("123 -> Tag.name('myNumber') -> Tag.getName", '"myNumber"');
   });
 
-  describe("description", () => {
-    testEvalToBe(
-      "123 -> Tag.description('myNumber') -> Tag.getDescription",
-      '"myNumber"'
-    );
+  describe("doc", () => {
+    testEvalToBe("123 -> Tag.doc('myNumber') -> Tag.getDoc", '"myNumber"');
   });
 
   describe("all", () => {
     testEvalToBe(
-      "123 -> Tag.name('myName') -> Tag.description('myDescription') -> Tag.all",
-      '{name: "myName",description: "myDescription"}'
+      "123 -> Tag.name('myName') -> Tag.doc('myDoc') -> Tag.all",
+      '{name: "myName",doc: "myDoc"}'
     );
   });
 
@@ -25,14 +22,14 @@ describe("Tags", () => {
 
   describe("omit", () => {
     testEvalToBe(
-      "123 -> Tag.name('myName') -> Tag.description('myDescription') -> Tag.format('.2%') -> Tag.omit(['name', 'description']) -> Tag.all",
+      "123 -> Tag.name('myName') -> Tag.doc('myDoc') -> Tag.format('.2%') -> Tag.omit(['name', 'doc']) -> Tag.all",
       '{numberFormat: ".2%"}'
     );
   });
 
   describe("clear", () => {
     testEvalToBe(
-      "123 -> Tag.name('myName') -> Tag.description('myDescription') -> Tag.format('.2%') -> Tag.clear -> Tag.all",
+      "123 -> Tag.name('myName') -> Tag.doc('myDoc') -> Tag.format('.2%') -> Tag.clear -> Tag.all",
       "{}"
     );
   });
@@ -50,12 +47,12 @@ x
   testEvalToBe(
     `
 @name("five")
-@description("This is five")
+@doc("This is five")
 x = 5
 
 x
 `,
-    '5, with params name: "five", description: "This is five"'
+    '5, with params name: "five", doc: "This is five"'
   );
 
   testEvalToBe(

diff --git a/packages/squiggle-lang/src/fr/calculator.ts b/packages/squiggle-lang/src/fr/calculator.ts
@@ -83,7 +83,7 @@ export const library = [
           return validateCalculator({
             fn: value,
             title: title || tags.value.name || undefined,
-            description: description || tags.value.description || undefined,
+            description: description || tags.value.doc || undefined,
             inputs: inputs || value.defaultInputs(),
             autorun: autorun === null || autorun === undefined ? true : autorun,
             sampleCount: sampleCount || undefined,

diff --git a/packages/squiggle-lang/src/fr/tag.ts b/packages/squiggle-lang/src/fr/tag.ts
@@ -116,22 +116,22 @@ export const library = [
     ],
   }),
   maker.make({
-    name: "description",
-    description: `Adds a description to a value. This is useful for documenting what a value represents, or how it was calculated.`,
+    name: "doc",
+    description: `Adds text documentation to a value. This is useful for documenting what a value represents or how it was calculated.`,
     definitions: [
       makeDefinition(
         [frAny({ genericName: "A" }), frString],
         frAny({ genericName: "A" }),
-        ([value, description]) => value.mergeTags({ description }),
+        ([value, doc]) => value.mergeTags({ doc }),
         { isDecorator: true }
       ),
     ],
   }),
   maker.make({
-    name: "getDescription",
+    name: "getDoc",
     definitions: [
       makeDefinition([frAny()], frString, ([value]) => {
-        return value.tags?.value.description || "";
+        return value.tags?.value.doc || "";
       }),
     ],
   }),

diff --git a/packages/squiggle-lang/src/public/SqValue/SqTags.ts b/packages/squiggle-lang/src/public/SqValue/SqTags.ts
@@ -12,8 +12,8 @@ export class SqTags {
     return this.tags.name();
   }
 
-  description(): string | undefined {
-    return this.tags.description();
+  doc(): string | undefined {
+    return this.tags.doc();
   }
 
   showAs(): SqValue | undefined {

diff --git a/packages/squiggle-lang/src/value/valueTags.ts b/packages/squiggle-lang/src/value/valueTags.ts
@@ -5,7 +5,7 @@ import { Value, vBool, vString } from "./index.js";
 
 export type ValueTagsType = {
   name?: string;
-  description?: string;
+  doc?: string;
   showAs?: Value;
   numberFormat?: string;
   dateFormat?: string;
@@ -16,7 +16,7 @@ type ValueTagsTypeName = keyof ValueTagsType;
 
 const valueTagsTypeNames: ValueTagsTypeName[] = [
   "name",
-  "description",
+  "doc",
   "showAs",
   "numberFormat",
   "dateFormat",
@@ -49,8 +49,8 @@ export class ValueTags {
     if (value.name) {
       result.push(["name", vString(value.name)]);
     }
-    if (value.description) {
-      result.push(["description", vString(value.description)]);
+    if (value.doc) {
+      result.push(["doc", vString(value.doc)]);
     }
     if (value.showAs) {
       result.push(["showAs", value.showAs]);
@@ -100,8 +100,8 @@ export class ValueTags {
     return this.value.name;
   }
 
-  description() {
-    return this.value.description;
+  doc() {
+    return this.value.doc;
   }
 
   showAs() {

diff --git a/packages/website/scripts/generateModulePages.mjs b/packages/website/scripts/generateModulePages.mjs
@@ -22,13 +22,13 @@ Tags can be added to variables either by using their name \`Tag.[name]\` or by u
 ## Examples
 <SquiggleEditor
 defaultCode={\`@name("My Great Function") // Decorator syntax to add a name tag
-@description("This is an example function.")
+@doc("This is an example function.")
 @showAs(Calculator) // Show this as a simple calculator in the Playground
 exampleFn(f) = f^2
   
 myVarTags = Tag.all(exampleFn)
   
-description = Tag.getDescription(exampleFn)
+docs = Tag.getDoc(exampleFn)
   
 @hide // Hide this variable in the Playground
 helperFn(f) = f \`}/>