did them all

Signed-off-by: Jess Frazelle <[email protected]>

nexus/src/external_api/http_entrypoints.rs

@@ -1856,7 +1856,10 @@ async fn vpc_subnets_delete_subnet(
 }
 
 /**
- * Update a VPC Subnet.
+ * Update a subnet
+ *
+ * Updates the specified subnet in a VPC by setting the values of the parameters passed. Any
+ * parameters not provided are left unchanged.
  */
 #[endpoint {
     method = PUT,
@@ -1888,7 +1891,11 @@ async fn vpc_subnets_put_subnet(
     apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await
 }
 
-/// List network interfaces in a VPC subnet.
+/** List network interfaces
+ *
+ * Returns a list of network interfaces in a subnet. The network interfaces are
+ * returned sorted alphabetically by name.
+ */
 #[endpoint {
     method = GET,
     path = "/organizations/{organization_name}/projects/{project_name}/vpcs/{vpc_name}/subnets/{subnet_name}/network-interfaces",
@@ -1929,7 +1936,10 @@ async fn subnet_network_interfaces_get(
  */
 
 /**
- * List firewall rules for a VPC.
+ * List firewall rules
+ *
+ * Returns a list of firewall rules in a VPC. The firewall rules are returned sorted
+ * alphabetically by name.
  */
 #[endpoint {
     method = GET,
@@ -1962,7 +1972,11 @@ async fn vpc_firewall_rules_get(
 }
 
 /**
- * Replace the firewall rules for a VPC
+ * Replace the firewall rules
+ *
+ * Replaces the firewall rules in a VPC with the specified rules. Any existing
+ * firewall rules are overwritten by the new rules.
+ * TODO: write a bit about the semantics of this operation since it is finiky.
  */
 #[endpoint {
     method = PUT,
@@ -2000,7 +2014,9 @@ async fn vpc_firewall_rules_put(
  */
 
 /**
- * List VPC Custom and System Routers
+ * List routers
+ *
+ * Returns a list of routers in a VPC. The routers are returned sorted alphabetically by name.
  */
 #[endpoint {
     method = GET,
@@ -2046,7 +2062,9 @@ struct VpcRouterPathParam {
 }
 
 /**
- * Get a VPC Router
+ * Get a router
+ *
+ * Returns details of the router with the specified name.
  */
 #[endpoint {
     method = GET,
@@ -2075,7 +2093,9 @@ async fn vpc_routers_get_router(
 }
 
 /**
- * Create a VPC Router
+ * Create a router
+ *
+ * Creates a new router in a VPC.
  */
 #[endpoint {
     method = POST,
@@ -2106,7 +2126,9 @@ async fn vpc_routers_post(
 }
 
 /**
- * Delete a router from its VPC
+ * Delete a router
+ *
+ * Deletes the router with the specified name. This operation cannot be undone.
  */
 #[endpoint {
     method = DELETE,
@@ -2135,7 +2157,10 @@ async fn vpc_routers_delete_router(
 }
 
 /**
- * Update a VPC Router
+ * Update a router
+ *
+ * Updates the specified router by setting the values of the parameters passed.
+ * Any parameters not specified are left unchanged.
  */
 #[endpoint {
     method = PUT,
@@ -2170,7 +2195,10 @@ async fn vpc_routers_put_router(
  */
 
 /**
- * List a Router's routes
+ * List routes
+ *
+ * Returns a list of routes for the specified router. The routes are returned
+ * in alphabetical order by route name.
  */
 #[endpoint {
     method = GET,
@@ -2218,7 +2246,9 @@ struct RouterRoutePathParam {
 }
 
 /**
- * Get a VPC Router route
+ * Get a route
+ *
+ * Returns details of the route with the specified name in the specified router.
  */
 #[endpoint {
     method = GET,
@@ -2248,7 +2278,9 @@ async fn routers_routes_get_route(
 }
 
 /**
- * Create a VPC Router
+ * Create a route
+ *
+ * Creates a new route in the specified router.
  */
 #[endpoint {
     method = POST,
@@ -2280,7 +2312,10 @@ async fn routers_routes_post(
 }
 
 /**
- * Delete a route from its router
+ * Delete a route
+ *
+ * Permanently deletes the specified route from the specified router.
+ * TODO: We might want some more detail here on the behavior of this endpoint.
  */
 #[endpoint {
     method = DELETE,
@@ -2310,7 +2345,10 @@ async fn routers_routes_delete_route(
 }
 
 /**
- * Update a Router route
+ * Update a route
+ *
+ * Updates the specified route in the specified router by setting the values of the parameters
+ * passed. Any parameters not provided are left unchanged.
  */
 #[endpoint {
     method = PUT,
@@ -2346,7 +2384,9 @@ async fn routers_routes_put_route(
  */
 
 /**
- * List racks in the system.
+ * List racks
+ *
+ * Returns a list of racks. The racks are returned sorted by name alphabetically.
  */
 #[endpoint {
     method = GET,
@@ -2379,7 +2419,9 @@ struct RackPathParam {
 }
 
 /**
- * Fetch information about a particular rack.
+ * Fetch a rack
+ *
+ * Returns details of the specified rack.
  */
 #[endpoint {
     method = GET,
@@ -2405,7 +2447,9 @@ async fn hardware_racks_get_rack(
  */
 
 /**
- * List sleds in the system.
+ * List all sleds
+ *
+ * Returns a list of sleds. The sleds are returned sorted by name alphabetically.
  */
 #[endpoint {
     method = GET,
@@ -2441,7 +2485,9 @@ struct SledPathParam {
 }
 
 /**
- * Fetch information about a sled in the system.
+ * Fetch a sled
+ *
+ * Returns details of the specified sled.
  */
 #[endpoint {
     method = GET,
@@ -2468,6 +2514,9 @@ async fn hardware_sleds_get_sled(
 
 /**
  * Refresh update metadata
+ *
+ * Refreshes the update metadata. If there is a new software update, then the server
+ * will be aware of it and can optionally perform the update.
  */
 #[endpoint {
      method = POST,
@@ -2491,12 +2540,15 @@ async fn updates_refresh(
  */
 
 /**
- * List all sagas (for debugging)
+ * List all sagas
+ *
+ * Returns a list of sagas. The sagas are returned sorted by name alphabetically.
+ * This endpoint is only for debugging.
  */
 #[endpoint {
     method = GET,
     path = "/sagas",
-    tags = ["sagas"],
+    tags = ["sagas", "hidden"],
 }]
 async fn sagas_get(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -2523,12 +2575,14 @@ struct SagaPathParam {
 }
 
 /**
- * Fetch information about a single saga (for debugging)
+ * Fetch a saga
+ *
+ * Returns details of the specified saga.
  */
 #[endpoint {
     method = GET,
     path = "/sagas/{saga_id}",
-    tags = ["sagas"],
+    tags = ["sagas", "hidden"],
 }]
 async fn sagas_get_saga(
     rqctx: Arc<RequestContext<Arc<ServerContext>>>,
@@ -2549,7 +2603,9 @@ async fn sagas_get_saga(
  */
 
 /**
- * List the built-in system users
+ * List users
+ *
+ * Returns a list of users. The users are returned sorted by name alphabetically.
  */
 #[endpoint {
     method = GET,
@@ -2588,7 +2644,11 @@ struct UserPathParam {
 }
 
 /**
- * Fetch a specific built-in system user
+ * Fetch a user
+ *
+ * Returns details of the specified user. If you pass `me` as the `user_name`,
+ * this function returns details of the authenticated user.
+ * TODO: Can we make the above true.
  */
 #[endpoint {
     method = GET,
@@ -2613,6 +2673,9 @@ async fn users_get_user(
 
 /**
  * List all timeseries schema
+ *
+ * Returns a list of all timeseries schemas. The schemas are returned sorted by
+ * name alphabetically.
  */
 #[endpoint {
     method = GET,
@@ -2648,7 +2711,10 @@ struct RolePage {
 }
 
 /**
- * List the built-in roles
+ * List roles
+ *
+ * Returns a list of roles. The roles are returned sorted by name alphabetically.
+ * For now, these are only the built-in roles.
  */
 #[endpoint {
     method = GET,
@@ -2706,7 +2772,9 @@ struct RolePathParam {
 }
 
 /**
- * Fetch a specific built-in role
+ * Fetch a role
+ *
+ * Returns details of the specified role.
  */
 #[endpoint {
     method = GET,