docs: Descriptions in segments (#8622)

Author: igorlukanin

docs/pages/reference/data-model/cube.mdx

@@ -137,17 +137,20 @@ cubes:
 
 ### `description`
 
-Use a description in your cubes to allow your team to better understand what
-this cube is about. It is a very simple and yet useful tool that gives a hint to
-everyone and makes sure data is interpreted correctly by users.
+This parameter provides a human-readable description of a cube.
+When applicable, it will be displayed in [Playground][ref-playground] and exposed
+to data consumers via [APIs and integrations][ref-apis].
+
+A description can give a hint both to your team and end users, making sure they
+interpret the data correctly. 
 
 <CodeTabs>
 
 ```javascript
 cube(`orders`, {
   sql_table: `orders`,
   title: `Product Orders`,
-  description: `All orders related information`,
+  description: `All orders-related information`,
 });
 ```
 
@@ -156,7 +159,7 @@ cubes:
   - name: orders
     sql_table: orders
     title: Product Orders
-    description: All orders related information
+    description: All orders-related information
 ```
 
 </CodeTabs>
@@ -580,6 +583,7 @@ cubes:
 
 </CodeTabs>
 
+
 [ref-config-driverfactory]: /reference/configuration/config#driverfactory
 [ref-config-ext-ctx]: /reference/configuration/config#extend_context
 [ref-config-queryrewrite]: /reference/configuration/config#queryrewrite
@@ -591,8 +595,10 @@ cubes:
 [ref-restapi-sql]: /reference/rest-api#v1sql
 [ref-sec-ctx]: /product/auth/context
 [ref-naming]: /product/data-modeling/syntax#naming
+[ref-playground]: /product/workspace/playground
+[ref-apis]: /product/apis-integrations
 [ref-ref-measures]: /reference/data-model/measures
 [ref-ref-dimensions]: /reference/data-model/dimensions
 [ref-ref-segments]: /reference/data-model/segments
 [ref-ref-joins]: /reference/data-model/joins
-[ref-ref-pre-aggs]: /reference/data-model/pre-aggregations
+[ref-ref-pre-aggs]: /reference/data-model/pre-aggregations

docs/pages/reference/data-model/dimensions.mdx

@@ -14,7 +14,7 @@ Any dimension should have the following properties: `name`, `sql` and `type`.
 
 ## Parameters
 
-### name
+### `name`
 
 The `name` parameter serves as the identifier of a dimension. It must be unique
 among all dimensions, measures, and segments within a cube and follow the
@@ -56,7 +56,7 @@ cubes:
 
 </CodeTabs>
 
-### case
+### `case`
 
 The `case` statement is used to define dimensions based on SQL conditions.
 
@@ -152,9 +152,11 @@ cube(`products`, {
 });
 ```
 
-### description
+### `description`
 
-You can add details to a dimension's definition via the `description` property:
+This parameter provides a human-readable description of a dimension.
+When applicable, it will be displayed in [Playground][ref-playground] and exposed
+to data consumers via [APIs and integrations][ref-apis].
 
 <CodeTabs>
 
@@ -186,7 +188,7 @@ cubes:
 
 </CodeTabs>
 
-### format
+### `format`
 
 `format` is an optional parameter. It is used to format the output of dimensions
 in different ways, for example, a link for `external_url`. Please refer to the
@@ -223,7 +225,7 @@ cubes:
 
 </CodeTabs>
 
-### meta
+### `meta`
 
 Custom metadata. Can be used to pass any information to the frontend.
 
@@ -260,7 +262,7 @@ cubes:
 
 </CodeTabs>
 
-### primary_key
+### `primary_key`
 
 Specify which dimension is a primary key for a cube. The default value is
 `false`.
@@ -304,7 +306,7 @@ cubes:
 
 </CodeTabs>
 
-### propagate_filters_to_sub_query
+### `propagate_filters_to_sub_query`
 
 When this statement is set to `true`, the filters applied to the query will be
 passed to the [subquery][self-subquery].
@@ -341,7 +343,7 @@ cubes:
 
 </CodeTabs>
 
-### public
+### `public`
 
 <InfoBox>
 
@@ -383,7 +385,7 @@ cubes:
 
 </CodeTabs>
 
-### sql
+### `sql`
 
 `sql` is a required parameter. It can take any valid SQL expression depending on
 the `type` of the dimension. Please refer to the [Dimension
@@ -418,7 +420,7 @@ cube(`orders`, {
 
 </CodeTabs>
 
-### sub_query
+### `sub_query`
 
 The `sub_query` statement allows you to reference a measure in a dimension. It's
 an advanced concept and you can learn more about it [here][ref-subquery].
@@ -453,7 +455,7 @@ cubes:
 
 </CodeTabs>
 
-### title
+### `title`
 
 You can use the `title` parameter to change a dimension's displayed name. By
 default, Cube will humanize your dimension key to create a display name. In
@@ -489,7 +491,7 @@ cubes:
 
 </CodeTabs>
 
-### type
+### `type`
 
 `type` is a required parameter. There are various types that can be assigned to
 a dimension. Please refer to the [Dimension Types][ref-schema-ref-dims-types]
@@ -523,6 +525,7 @@ cubes:
 
 </CodeTabs>
 
+
 [ref-schema-ref-joins]: /reference/data-model/joins
 [ref-subquery]: /product/data-modeling/concepts/calculated-members#subquery-dimensions
 [self-subquery]: #sub-query
@@ -531,3 +534,5 @@ cubes:
   /reference/data-model/types-and-formats#dimension-types
 [ref-schema-ref-dims-formats]:
   /reference/data-model/types-and-formats#dimension-formats
+[ref-playground]: /product/workspace/playground
+[ref-apis]: /product/apis-integrations

docs/pages/reference/data-model/measures.mdx

@@ -58,7 +58,9 @@ cubes:
 
 ### `description`
 
-You can add details to a measure’s definition via the `description` parameter:
+This parameter provides a human-readable description of a measure.
+When applicable, it will be displayed in [Playground][ref-playground] and exposed
+to data consumers via [APIs and integrations][ref-apis].
 
 <CodeTabs>
 
@@ -70,7 +72,7 @@ cube(`orders`, {
     orders_count: {
       sql: `id`,
       type: `count`,
-      description: `count of all orders`,
+      description: `Count of all orders`,
     },
   },
 });
@@ -83,7 +85,7 @@ cubes:
 
     measures:
       - name: orders_count
-        description: count of all orders
+        description: Count of all orders
         sql: id
         type: count
 ```
@@ -530,9 +532,12 @@ cubes:
 You can create calculated measures from several joined cubes. In this case, a
 join will be created automatically.
 
+
 [ref-schema-ref-types-formats-measures-types]:
   /reference/data-model/types-and-formats#measure-types
 [ref-schema-ref-types-formats-measures-formats]:
   /reference/data-model/types-and-formats#measure-formats
 [ref-drilldowns]: /guides/recipes/data-exploration/drilldowns
 [ref-naming]: /product/data-modeling/syntax#naming
+[ref-playground]: /product/workspace/playground
+[ref-apis]: /product/apis-integrations

docs/pages/reference/data-model/segments.mdx

@@ -102,7 +102,7 @@ After defining a segment, you can pass it in [query object][ref-backend-query]:
 
 ## Parameters
 
-### name
+### `name`
 
 The `name` parameter serves as the identifier of a segment. It must be unique
 among all segments, dimensions, and measures within a cube and follow the
@@ -134,7 +134,41 @@ cubes:
 
 </CodeTabs>
 
-### public
+### `description`
+
+This parameter provides a human-readable description of a segment.
+When applicable, it will be displayed in [Playground][ref-playground] and exposed
+to data consumers via [APIs and integrations][ref-apis].
+
+<CodeTabs>
+
+```javascript
+cube(`users`, {
+  // ...
+
+  segments: {
+    sf_users: {
+      sql: `${CUBE}.location = 'San Francisco'`,
+      description: `Users from San Francisco`
+    }
+  }
+})
+```
+
+```yaml
+cubes:
+  - name: users
+    # ...
+
+    segments:
+      - name: sf_users
+        sql: "{CUBE}.location = 'San Francisco'"
+        description: Users from San Francisco
+```
+
+</CodeTabs>
+
+### `public`
 
 The `public` property is used to manage the visibility of a segment. Valid
 values for `public` are `true` and `false`. When set to `false`, this segment
@@ -164,7 +198,7 @@ cubes:
 
 </CodeTabs>
 
-### sql
+### `sql`
 
 The `sql` parameter defines how a segment would filter out a subset of data. It
 takes any SQL expression that would be valid within a `WHERE` statement.
@@ -301,6 +335,9 @@ cubes:
 
 </CodeTabs>
 
+
 [ref-backend-query]: /product/apis-integrations/rest-api/query-format
 [ref-schema-gen]: /guides/recipes/code-reusability/schema-generation
 [ref-naming]: /product/data-modeling/syntax#naming
+[ref-playground]: /product/workspace/playground
+[ref-apis]: /product/apis-integrations

docs/pages/reference/data-model/view.mdx

@@ -34,9 +34,12 @@ views:
 
 ### `description`
 
-A description of the view allows your team to better understand what its purpose
-is. It is a very simple and yet useful tool that gives a hint to everyone and
-ensures that data is interpreted correctly by users.
+This parameter provides a human-readable description of a view.
+When applicable, it will be displayed in [Playground][ref-playground] and exposed
+to data consumers via [APIs and integrations][ref-apis].
+
+A description can give a hint both to your team and end users, making sure they
+interpret the data correctly. 
 
 <CodeTabs>
 
@@ -302,8 +305,11 @@ matching algorithm used for Cubes. As a consequence, all measures and dimensions
 included in pre-aggregation should be leaf members in order to be matched by
 view query.
 
+
 [ref-recipe-control-access-cubes-views]:
   /guides/recipes/access-control/controlling-access-to-cubes-and-views
 [ref-schema-joins-direction]:
   /product/data-modeling/concepts/working-with-joins#directions-of-joins
 [ref-naming]: /product/data-modeling/syntax#naming
+[ref-playground]: /product/workspace/playground
+[ref-apis]: /product/apis-integrations