Lock down mac os platform type visibility in the rest of GPUI

Add documentation to all platform types

crates/gpui/src/platform/app_menu.rs

@@ -1,30 +1,49 @@
 use crate::{Action, AppContext, Platform};
 use util::ResultExt;
 
+/// A menu of the application, either a main menu or a submenu
 pub struct Menu<'a> {
+    /// The name of the menu
     pub name: &'a str,
+
+    /// The items in the menu
     pub items: Vec<MenuItem<'a>>,
 }
 
+/// The different kinds of items that can be in a menu
 pub enum MenuItem<'a> {
+    /// A separator between items
     Separator,
+
+    /// A submenu
     Submenu(Menu<'a>),
+
+    /// An action that can be performed
     Action {
+        /// The name of this menu item
         name: &'a str,
+
+        /// the action to perform when this menu item is selected
         action: Box<dyn Action>,
+
+        /// The OS Action that corresponds to this action, if any
+        /// See [`OsAction`] for more information
         os_action: Option<OsAction>,
     },
 }
 
 impl<'a> MenuItem<'a> {
+    /// Creates a new menu item that is a separator
     pub fn separator() -> Self {
         Self::Separator
     }
 
+    /// Creates a new menu item that is a submenu
     pub fn submenu(menu: Menu<'a>) -> Self {
         Self::Submenu(menu)
     }
 
+    /// Creates a new menu item that invokes an action
     pub fn action(name: &'a str, action: impl Action) -> Self {
         Self::Action {
             name,
@@ -33,6 +52,7 @@ impl<'a> MenuItem<'a> {
         }
     }
 
+    /// Creates a new menu item that invokes an action and has an OS action
     pub fn os_action(name: &'a str, action: impl Action, os_action: OsAction) -> Self {
         Self::Action {
             name,
@@ -42,13 +62,31 @@ impl<'a> MenuItem<'a> {
     }
 }
 
+// TODO: As part of the global selections refactor, these should
+// be moved to GPUI-provided actions that make this association
+// without leaking the platform details to GPUI users
+
+/// OS actions are actions that are recognized by the operating system
+/// This allows the operating system to provide specialized behavior for
+/// these actions
 #[derive(Copy, Clone, Eq, PartialEq)]
 pub enum OsAction {
+    /// The 'cut' action
     Cut,
+
+    /// The 'copy' action
     Copy,
+
+    /// The 'paste' action
     Paste,
+
+    /// The 'select all' action
     SelectAll,
+
+    /// The 'undo' action
     Undo,
+
+    /// The 'redo' action
     Redo,
 }