From f55d10c3619a5f7667bc18985884b8759f27c7f3 Mon Sep 17 00:00:00 2001
From: Luigi Teschio <gigitux@gmail.com>
Date: Wed, 4 Dec 2024 15:20:57 +0100
Subject: [PATCH] improve documentation for fields package

---
 packages/fields/README.md                     | 56 +++++++------------
 packages/fields/src/actions/delete-post.tsx   |  3 +
 .../fields/src/actions/duplicate-pattern.tsx  |  3 +
 .../src/actions/duplicate-post.native.tsx     |  3 -
 .../fields/src/actions/duplicate-post.tsx     |  9 ++-
 .../src/actions/duplicate-template-part.tsx   |  4 +-
 .../src/actions/export-pattern.native.tsx     |  3 -
 .../fields/src/actions/export-pattern.tsx     |  3 +
 packages/fields/src/actions/index.ts          |  3 -
 .../src/actions/permanently-delete-post.tsx   |  3 +
 packages/fields/src/actions/rename-post.tsx   |  3 +
 .../src/actions/reorder-page.native.tsx       |  3 -
 packages/fields/src/actions/reorder-page.tsx  |  3 +
 packages/fields/src/actions/reset-post.tsx    |  3 +
 packages/fields/src/actions/restore-post.tsx  |  3 +
 packages/fields/src/actions/trash-post.tsx    |  3 +
 .../src/actions/view-post-revisions.tsx       |  3 +
 packages/fields/src/actions/view-post.tsx     |  3 +
 .../fields/src/fields/featured-image/index.ts |  3 +
 packages/fields/src/fields/order/index.ts     |  3 +
 packages/fields/src/fields/parent/index.ts    |  2 +-
 packages/fields/src/fields/password/index.tsx |  2 +-
 packages/fields/src/fields/slug/index.ts      |  3 +
 packages/fields/src/fields/template/index.ts  |  4 +-
 packages/fields/src/fields/title/index.ts     |  3 +
 packages/fields/src/index.native.ts           |  2 -
 26 files changed, 79 insertions(+), 57 deletions(-)
 delete mode 100644 packages/fields/src/actions/duplicate-post.native.tsx
 delete mode 100644 packages/fields/src/actions/export-pattern.native.tsx
 delete mode 100644 packages/fields/src/actions/reorder-page.native.tsx

diff --git a/packages/fields/README.md b/packages/fields/README.md
index 2fc512b9432645..144982361be252 100644
--- a/packages/fields/README.md
+++ b/packages/fields/README.md
@@ -41,55 +41,43 @@ Date field for BasePost.
 
 ### deletePost
 
-Undocumented declaration.
+Delete action for Templates, Patterns and Template Parts.
 
 ### duplicatePattern
 
-Undocumented declaration.
+Duplicate action for Pattern.
 
 ### duplicatePost
 
-Undocumented declaration.
-
-### duplicatePostNative
-
-Undocumented declaration.
+Duplicate action for BasePost.
 
 ### duplicateTemplatePart
 
-This action is used to duplicate a template part.
-
-_Type_
-
--   `Action< TemplatePart >`
+Duplicate action for TemplatePart.
 
 ### exportPattern
 
-Undocumented declaration.
-
-### exportPatternNative
-
-Undocumented declaration.
+Export action as JSON for Pattern.
 
 ### featuredImageField
 
-Undocumented declaration.
+Featured Image field for BasePost.
 
 ### orderField
 
-Undocumented declaration.
+Order field for BasePost.
 
 ### parentField
 
-This field is used to display the post parent.
+Parent field for BasePost.
 
 ### passwordField
 
-This field is used to display the post password.
+Password field for BasePost.
 
 ### permanentlyDeletePost
 
-Undocumented declaration.
+Delete action for PostWithPermissions.
 
 ### PostType
 
@@ -97,27 +85,23 @@ Undocumented declaration.
 
 ### renamePost
 
-Undocumented declaration.
+Rename action for PostWithPermissions.
 
 ### reorderPage
 
-Undocumented declaration.
-
-### reorderPageNative
-
-Undocumented declaration.
+Reorder action for BasePost.
 
 ### resetPost
 
-Undocumented declaration.
+Reset action for Template and TemplatePart.
 
 ### restorePost
 
-Undocumented declaration.
+Restore action for PostWithPermissions.
 
 ### slugField
 
-Undocumented declaration.
+Slug field for BasePost.
 
 ### statusField
 
@@ -125,23 +109,23 @@ Status field for BasePost.
 
 ### templateField
 
-Undocumented declaration.
+Template field for BasePost.
 
 ### titleField
 
-Undocumented declaration.
+Title field for BasePost.
 
 ### trashPost
 
-Undocumented declaration.
+Trash action for PostWithPermissions.
 
 ### viewPost
 
-Undocumented declaration.
+View post action for BasePost.
 
 ### viewPostRevisions
 
-Undocumented declaration.
+View post revisions action for Post.
 
 <!-- END TOKEN(Autogenerated API docs) -->
 
diff --git a/packages/fields/src/actions/delete-post.tsx b/packages/fields/src/actions/delete-post.tsx
index d3a469d7f83ab4..4a94796b6f0bdf 100644
--- a/packages/fields/src/actions/delete-post.tsx
+++ b/packages/fields/src/actions/delete-post.tsx
@@ -203,4 +203,7 @@ const deletePostAction: Action< Template | TemplatePart | Pattern > = {
 	},
 };
 
+/**
+ * Delete action for Templates, Patterns and Template Parts.
+ */
 export default deletePostAction;
diff --git a/packages/fields/src/actions/duplicate-pattern.tsx b/packages/fields/src/actions/duplicate-pattern.tsx
index bf2820f951dbad..274f57b0fe19dc 100644
--- a/packages/fields/src/actions/duplicate-pattern.tsx
+++ b/packages/fields/src/actions/duplicate-pattern.tsx
@@ -37,4 +37,7 @@ const duplicatePattern: Action< Pattern > = {
 	},
 };
 
+/**
+ * Duplicate action for Pattern.
+ */
 export default duplicatePattern;
diff --git a/packages/fields/src/actions/duplicate-post.native.tsx b/packages/fields/src/actions/duplicate-post.native.tsx
deleted file mode 100644
index 5468aa649abbd4..00000000000000
--- a/packages/fields/src/actions/duplicate-post.native.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-const duplicatePost = undefined;
-
-export default duplicatePost;
diff --git a/packages/fields/src/actions/duplicate-post.tsx b/packages/fields/src/actions/duplicate-post.tsx
index fd7e0ae9de4ad1..5f079b5132c600 100644
--- a/packages/fields/src/actions/duplicate-post.tsx
+++ b/packages/fields/src/actions/duplicate-post.tsx
@@ -37,8 +37,8 @@ const duplicatePost: Action< BasePost > = {
 		const [ item, setItem ] = useState< BasePost >( {
 			...items[ 0 ],
 			title: sprintf(
-				/* translators: %s: Existing template title */
-				_x( '%s (Copy)', 'template' ),
+				/* translators: %s: Existing post title */
+				_x( '%s (Copy)', 'post' ),
 				getItemTitle( items[ 0 ] )
 			),
 		} );
@@ -104,7 +104,7 @@ const duplicatePost: Action< BasePost > = {
 
 				createSuccessNotice(
 					sprintf(
-						// translators: %s: Title of the created post or template, e.g: "Hello world".
+						// translators: %s: Title of the created post, e.g: "Hello world".
 						__( '"%s" successfully created.' ),
 						decodeEntities( newItem.title?.rendered || item.title )
 					),
@@ -171,4 +171,7 @@ const duplicatePost: Action< BasePost > = {
 	},
 };
 
+/**
+ * Duplicate action for BasePost.
+ */
 export default duplicatePost;
diff --git a/packages/fields/src/actions/duplicate-template-part.tsx b/packages/fields/src/actions/duplicate-template-part.tsx
index 44fcbad21f0733..795e40638a47a7 100644
--- a/packages/fields/src/actions/duplicate-template-part.tsx
+++ b/packages/fields/src/actions/duplicate-template-part.tsx
@@ -68,5 +68,7 @@ const duplicateTemplatePart: Action< TemplatePart > = {
 		);
 	},
 };
-
+/**
+ * Duplicate action for TemplatePart.
+ */
 export default duplicateTemplatePart;
diff --git a/packages/fields/src/actions/export-pattern.native.tsx b/packages/fields/src/actions/export-pattern.native.tsx
deleted file mode 100644
index c58cffcbd79e89..00000000000000
--- a/packages/fields/src/actions/export-pattern.native.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-const exportPattern = undefined;
-
-export default exportPattern;
diff --git a/packages/fields/src/actions/export-pattern.tsx b/packages/fields/src/actions/export-pattern.tsx
index b6be83eeda84b4..4a041e6ac73c3f 100644
--- a/packages/fields/src/actions/export-pattern.tsx
+++ b/packages/fields/src/actions/export-pattern.tsx
@@ -73,4 +73,7 @@ const exportPattern: Action< Pattern > = {
 	},
 };
 
+/**
+ * Export action as JSON for Pattern.
+ */
 export default exportPattern;
diff --git a/packages/fields/src/actions/index.ts b/packages/fields/src/actions/index.ts
index fc662206775316..cede3f1b59d1b3 100644
--- a/packages/fields/src/actions/index.ts
+++ b/packages/fields/src/actions/index.ts
@@ -1,13 +1,10 @@
 export { default as viewPost } from './view-post';
 export { default as reorderPage } from './reorder-page';
-export { default as reorderPageNative } from './reorder-page.native';
 export { default as duplicatePost } from './duplicate-post';
-export { default as duplicatePostNative } from './duplicate-post.native';
 export { default as renamePost } from './rename-post';
 export { default as resetPost } from './reset-post';
 export { default as duplicatePattern } from './duplicate-pattern';
 export { default as exportPattern } from './export-pattern';
-export { default as exportPatternNative } from './export-pattern.native';
 export { default as viewPostRevisions } from './view-post-revisions';
 export { default as permanentlyDeletePost } from './permanently-delete-post';
 export { default as restorePost } from './restore-post';
diff --git a/packages/fields/src/actions/permanently-delete-post.tsx b/packages/fields/src/actions/permanently-delete-post.tsx
index afbb84ae12c74c..688ba5b9918df8 100644
--- a/packages/fields/src/actions/permanently-delete-post.tsx
+++ b/packages/fields/src/actions/permanently-delete-post.tsx
@@ -115,4 +115,7 @@ const permanentlyDeletePost: Action< PostWithPermissions > = {
 	},
 };
 
+/**
+ * Delete action for PostWithPermissions.
+ */
 export default permanentlyDeletePost;
diff --git a/packages/fields/src/actions/rename-post.tsx b/packages/fields/src/actions/rename-post.tsx
index 5203328b46de53..be0e69db26cd80 100644
--- a/packages/fields/src/actions/rename-post.tsx
+++ b/packages/fields/src/actions/rename-post.tsx
@@ -139,4 +139,7 @@ const renamePost: Action< PostWithPermissions > = {
 	},
 };
 
+/**
+ * Rename action for PostWithPermissions.
+ */
 export default renamePost;
diff --git a/packages/fields/src/actions/reorder-page.native.tsx b/packages/fields/src/actions/reorder-page.native.tsx
deleted file mode 100644
index 61e4733b6c6bd9..00000000000000
--- a/packages/fields/src/actions/reorder-page.native.tsx
+++ /dev/null
@@ -1,3 +0,0 @@
-const reorderPage = undefined;
-
-export default reorderPage;
diff --git a/packages/fields/src/actions/reorder-page.tsx b/packages/fields/src/actions/reorder-page.tsx
index 1820884d8d8c73..cffc4b924c0a5d 100644
--- a/packages/fields/src/actions/reorder-page.tsx
+++ b/packages/fields/src/actions/reorder-page.tsx
@@ -122,4 +122,7 @@ const reorderPage: Action< BasePost > = {
 	RenderModal: ReorderModal,
 };
 
+/**
+ * Reorder action for BasePost.
+ */
 export default reorderPage;
diff --git a/packages/fields/src/actions/reset-post.tsx b/packages/fields/src/actions/reset-post.tsx
index 3e6b2e29b68b65..d8ac5730d6a166 100644
--- a/packages/fields/src/actions/reset-post.tsx
+++ b/packages/fields/src/actions/reset-post.tsx
@@ -292,4 +292,7 @@ const resetPostAction: Action< Template | TemplatePart > = {
 	},
 };
 
+/**
+ * Reset action for Template and TemplatePart.
+ */
 export default resetPostAction;
diff --git a/packages/fields/src/actions/restore-post.tsx b/packages/fields/src/actions/restore-post.tsx
index 874eca91fee113..6ea493a619ae80 100644
--- a/packages/fields/src/actions/restore-post.tsx
+++ b/packages/fields/src/actions/restore-post.tsx
@@ -131,4 +131,7 @@ const restorePost: Action< PostWithPermissions > = {
 	},
 };
 
+/**
+ * Restore action for PostWithPermissions.
+ */
 export default restorePost;
diff --git a/packages/fields/src/actions/trash-post.tsx b/packages/fields/src/actions/trash-post.tsx
index befbfb0ee7ffba..c0227996b5e866 100644
--- a/packages/fields/src/actions/trash-post.tsx
+++ b/packages/fields/src/actions/trash-post.tsx
@@ -195,4 +195,7 @@ const trashPost: Action< PostWithPermissions > = {
 	},
 };
 
+/**
+ * Trash action for PostWithPermissions.
+ */
 export default trashPost;
diff --git a/packages/fields/src/actions/view-post-revisions.tsx b/packages/fields/src/actions/view-post-revisions.tsx
index 75d4edfd73e18d..40eecde5771311 100644
--- a/packages/fields/src/actions/view-post-revisions.tsx
+++ b/packages/fields/src/actions/view-post-revisions.tsx
@@ -44,4 +44,7 @@ const viewPostRevisions: Action< Post > = {
 	},
 };
 
+/**
+ * View post revisions action for Post.
+ */
 export default viewPostRevisions;
diff --git a/packages/fields/src/actions/view-post.tsx b/packages/fields/src/actions/view-post.tsx
index 187faffafb5d3c..7517ab1f37cb33 100644
--- a/packages/fields/src/actions/view-post.tsx
+++ b/packages/fields/src/actions/view-post.tsx
@@ -27,4 +27,7 @@ const viewPost: Action< BasePost > = {
 	},
 };
 
+/**
+ * View post action for BasePost.
+ */
 export default viewPost;
diff --git a/packages/fields/src/fields/featured-image/index.ts b/packages/fields/src/fields/featured-image/index.ts
index 62d7e8240aded0..d6f22176fc6704 100644
--- a/packages/fields/src/fields/featured-image/index.ts
+++ b/packages/fields/src/fields/featured-image/index.ts
@@ -20,4 +20,7 @@ const featuredImageField: Field< BasePost > = {
 	enableSorting: false,
 };
 
+/**
+ * Featured Image field for BasePost.
+ */
 export default featuredImageField;
diff --git a/packages/fields/src/fields/order/index.ts b/packages/fields/src/fields/order/index.ts
index 984a94c6427fc6..121fcb9d0f3bdc 100644
--- a/packages/fields/src/fields/order/index.ts
+++ b/packages/fields/src/fields/order/index.ts
@@ -16,4 +16,7 @@ const orderField: Field< BasePost > = {
 	description: __( 'Determines the order of pages.' ),
 };
 
+/**
+ * Order field for BasePost.
+ */
 export default orderField;
diff --git a/packages/fields/src/fields/parent/index.ts b/packages/fields/src/fields/parent/index.ts
index 8b833e1d9369df..f974608710bf7e 100644
--- a/packages/fields/src/fields/parent/index.ts
+++ b/packages/fields/src/fields/parent/index.ts
@@ -21,6 +21,6 @@ const parentField: Field< BasePost > = {
 };
 
 /**
- * This field is used to display the post parent.
+ * Parent field for BasePost.
  */
 export default parentField;
diff --git a/packages/fields/src/fields/password/index.tsx b/packages/fields/src/fields/password/index.tsx
index dacd0d7435998a..3d45641b0efd0e 100644
--- a/packages/fields/src/fields/password/index.tsx
+++ b/packages/fields/src/fields/password/index.tsx
@@ -19,6 +19,6 @@ const passwordField: Field< BasePost > = {
 };
 
 /**
- * This field is used to display the post password.
+ * Password field for BasePost.
  */
 export default passwordField;
diff --git a/packages/fields/src/fields/slug/index.ts b/packages/fields/src/fields/slug/index.ts
index c43fcc679622ac..7311b1d10a66f6 100644
--- a/packages/fields/src/fields/slug/index.ts
+++ b/packages/fields/src/fields/slug/index.ts
@@ -19,4 +19,7 @@ const slugField: Field< BasePost > = {
 	render: SlugView,
 };
 
+/**
+ * Slug field for BasePost.
+ */
 export default slugField;
diff --git a/packages/fields/src/fields/template/index.ts b/packages/fields/src/fields/template/index.ts
index 7315b4ba349b1c..c419adedb537dd 100644
--- a/packages/fields/src/fields/template/index.ts
+++ b/packages/fields/src/fields/template/index.ts
@@ -14,9 +14,11 @@ const templateField: Field< BasePost > = {
 	id: 'template',
 	type: 'text',
 	label: __( 'Template' ),
-	getValue: ( { item } ) => item.template,
 	Edit: TemplateEdit,
 	enableSorting: false,
 };
 
+/**
+ * Template field for BasePost.
+ */
 export default templateField;
diff --git a/packages/fields/src/fields/title/index.ts b/packages/fields/src/fields/title/index.ts
index d8e6f25276d6b8..111980a1ca2b0a 100644
--- a/packages/fields/src/fields/title/index.ts
+++ b/packages/fields/src/fields/title/index.ts
@@ -21,4 +21,7 @@ const titleField: Field< BasePost > = {
 	enableHiding: false,
 };
 
+/**
+ * Title field for BasePost.
+ */
 export default titleField;
diff --git a/packages/fields/src/index.native.ts b/packages/fields/src/index.native.ts
index 33a26e3c2e6e27..e69de29bb2d1d6 100644
--- a/packages/fields/src/index.native.ts
+++ b/packages/fields/src/index.native.ts
@@ -1,2 +0,0 @@
-export * from './actions/duplicate-post.native';
-export * from './actions/reorder-page.native';