Merge pull request #529 from tableau/jac/docs-on-ids

Jac/docs on ids

docs/interfaces/column.html

@@ -121,10 +121,11 @@ <h3>field<wbr>Id</h3>
 					<div class="tsd-comment tsd-typography">
 						<dl class="tsd-comment-tags">
 							<dt>returns</dt>
-							<dd><p>The fieldId of the field in the column. In summary data, this includes the aggregation.
-									The fieldId is not stable across replacing data sources.
-									For example after replacing the data source [Clipboard_20210305T164000].[sum:Sales:qk] could become
-								[federated.12usuoq1171o1b1ebdyh60fjnev1].[sum:Sales:qk].</p>
+								<dd><p>The fieldId of the field in the column. This is a calculated string that is unique across all fields and datasources in the workbook. 
+								It does not directly correspond to any other object Id - it is a combination of DataSource.id, Field.id, and Field type information. 
+								(When retrieved as summary data, this includes the aggregation.)
+								This means the fieldID will change if the datasource is replaced: for example 
+								[Clipboard_20210305T164000].[sum:Sales:qk] could become [federated.12usuoq1171o1b1ebdyh60fjnev1].[sum:Sales:qk].</p>
 							</dd>
 							<dt>since</dt>
 							<dd><p>1.5.0</p>
@@ -144,8 +145,8 @@ <h3>field<wbr>Name</h3>
 					<div class="tsd-comment tsd-typography">
 						<dl class="tsd-comment-tags">
 							<dt>returns</dt>
-							<dd><p>The name of the field in the column. In summary data, this includes the aggregation.
-									The summary data field name is not stable across languages.
+							<dd><p>The name of the field in the column. In summary data, this includes the aggregation as localized text, therefore 
+								the summary data field name is not stable across languages.
 								For example, in an English version of Tableau, the field name might be SUM(Sales). In French, this would be SOMME(Sales).</p>
 							</dd>
 						</dl>
@@ -299,4 +300,4 @@ <h2>Legend</h2>
         ga('send', 'pageview');
     </script>
 </body>
-</html>
+</html>

docs/interfaces/field.html

@@ -187,7 +187,11 @@ <h3>id</h3>
 					<div class="tsd-comment tsd-typography">
 						<dl class="tsd-comment-tags">
 							<dt>returns</dt>
-							<dd><p>Unique string representing this field in this datasource.</p>
+							<dd><p>String that represents this field uniquely within this datasource. It is in the format 'a:generated-id:b[:c]',
+								where 'generated-id' is based on the first name given to the Field and a/b/c are type information. 
+								To match a  Field to a Column, use [this.DataSource.id][this.id] == Column.id
+								</p>
+							</dd>
 							</dd>
 						</dl>
 					</div>
@@ -430,4 +434,4 @@ <h2>Legend</h2>
         ga('send', 'pageview');
     </script>
 </body>
-</html>
+</html>