From 9a17ab9e4e98d8797a9912d3d5094c0e2bf9716f Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Thu, 12 Mar 2015 16:40:28 +0100 Subject: [PATCH] feat(docs): full usage example on landing page Related to #4 --- gen/youtube3/README.md | 62 ++++--- gen/youtube3/src/lib.rs | 340 +++++++++++++++++++++------------------ src/mako/lib.rs.mako | 8 +- src/mako/lib/lib.mako | 70 +++++--- src/mako/lib/mbuild.mako | 39 ++--- src/mako/lib/rbuild.mako | 2 +- src/mako/lib/util.py | 52 ++++-- 7 files changed, 333 insertions(+), 240 deletions(-) diff --git a/gen/youtube3/README.md b/gen/youtube3/README.md index 6be2ab1876b..b7820a9da5d 100644 --- a/gen/youtube3/README.md +++ b/gen/youtube3/README.md @@ -7,25 +7,25 @@ The `youtube3` library allows access to all features of *YouTube*. # Features -Handle the following *Resources* with ease ... - -* activities (*insert* and *list*) -* channel banners (*insert*) -* channel sections (*delete*, *insert*, *list* and *update*) -* channels (*list* and *update*) -* guide categories (*list*) -* i18n languages (*list*) -* i18n regions (*list*) -* live broadcasts (*bind*, *control*, *delete*, *insert*, *list*, *transition* and *update*) -* live streams (*delete*, *insert*, *list* and *update*) -* playlist items (*delete*, *insert*, *list* and *update*) -* playlists (*delete*, *insert*, *list* and *update*) -* search (*list*) -* subscriptions (*delete*, *insert* and *list*) -* thumbnails (*set*) -* video categories (*list*) -* videos (*delete*, *getRating*, *insert*, *list*, *rate* and *update*) -* watermarks (*set* and *unset*) +Handle the following *Resources* with ease from the central [hub](struct.YouTube.html) ... + +* activities ([*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.ActivityInsertMethodBuilder.html) and [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.ActivityListMethodBuilder.html)) +* channel banners ([*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelBannerInsertMethodBuilder.html)) +* channel sections ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelSectionDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelSectionInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelSectionListMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelSectionUpdateMethodBuilder.html)) +* channels ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelListMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelUpdateMethodBuilder.html)) +* guide categories ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.GuideCategoryListMethodBuilder.html)) +* i18n languages ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.I18nLanguageListMethodBuilder.html)) +* i18n regions ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.I18nRegionListMethodBuilder.html)) +* live broadcasts ([*bind*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastBindMethodBuilder.html), [*control*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastControlMethodBuilder.html), [*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastListMethodBuilder.html), [*transition*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastTransitionMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveBroadcastUpdateMethodBuilder.html)) +* live streams ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveStreamDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveStreamInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveStreamListMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.LiveStreamUpdateMethodBuilder.html)) +* playlist items ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemListMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemUpdateMethodBuilder.html)) +* playlists ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistListMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistUpdateMethodBuilder.html)) +* search ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.SearchListMethodBuilder.html)) +* subscriptions ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.SubscriptionDeleteMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.SubscriptionInsertMethodBuilder.html) and [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.SubscriptionListMethodBuilder.html)) +* thumbnails ([*set*](http://byron.github.io/google-apis-rs/youtube3/struct.ThumbnailSetMethodBuilder.html)) +* video categories ([*list*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoCategoryListMethodBuilder.html)) +* videos ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoDeleteMethodBuilder.html), [*getrating*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoGetRatingMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoListMethodBuilder.html), [*rate*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoRateMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoUpdateMethodBuilder.html)) +* watermarks ([*set*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkSetMethodBuilder.html) and [*unset*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkUnsetMethodBuilder.html)) Everything else about the *YouTube* API can be found at the [official documentation site](https://developers.google.com/youtube/v3). @@ -34,15 +34,15 @@ Everything else about the *YouTube* API can be found at the The API is structured into the following primary items: -* **Hub** +* **[Hub](struct.YouTube.html)** * a central object to maintain state and allow accessing all *Activities* -* **Resources** +* **[Resources](cmn/trait.Resource.html)** * primary types that you can apply *Activities* to * a collection of properties and *Parts* - * **Parts** + * **[Parts](cmn/trait.Part.html)** * a collection of properties * never directly used in *Activities* -* **Activities** +* **[Activities](cmn/trait.MethodBuilder.html)** * operations to apply to *Resources* Generally speaking, you can invoke *Activities* like this: @@ -77,7 +77,6 @@ extern crate hyper; extern crate "yup-oauth2" as oauth2; extern crate "rustc-serialize" as rustc_serialize; extern crate youtube3; - use std::default::Default; use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; # use youtube3::YouTube; @@ -93,8 +92,21 @@ let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate, hyper::Client::new(), ::default(), None); let mut hub = YouTube::new(hyper::Client::new(), auth); -``` +// You can configure optional parameters by calling the respective setters at will, and +// execute the final call using `doit()`. +// Values shown here are possibly random and not representative ! +let result = hub.live_broadcasts().list("part") + .page_token("sit") + .on_behalf_of_content_owner_channel("Stet") + .on_behalf_of_content_owner("sed") + .mine(false) + .max_results(83) + .id("kasd") + .broadcast_status("accusam") + .doit(); +// TODO: show how to handle the result ! +``` **TODO** Example calls - there should soon be a generator able to do that with proper inputs ## Handling Errors diff --git a/gen/youtube3/src/lib.rs b/gen/youtube3/src/lib.rs index 4193672655b..391532023e9 100644 --- a/gen/youtube3/src/lib.rs +++ b/gen/youtube3/src/lib.rs @@ -4,7 +4,7 @@ //! # Features //! -//! Handle the following *Resources* with ease ... +//! Handle the following *Resources* with ease from the central [hub](struct.YouTube.html) ... //! //! * [activities](struct.Activity.html) ([*insert*](struct.ActivityInsertMethodBuilder.html) and [*list*](struct.ActivityListMethodBuilder.html)) //! * channel banners ([*insert*](struct.ChannelBannerInsertMethodBuilder.html)) @@ -27,19 +27,21 @@ //! Everything else about the *YouTube* API can be found at the //! [official documentation site](https://developers.google.com/youtube/v3). //! +//! Not what you are looking for ? Find all other google APIs in their Rust [documentation index](../index.html). +//! //! # Structure of this Library //! //! The API is structured into the following primary items: //! -//! * **Hub** +//! * **[Hub](struct.YouTube.html)** //! * a central object to maintain state and allow accessing all *Activities* -//! * **Resources** +//! * **[Resources](cmn/trait.Resource.html)** //! * primary types that you can apply *Activities* to //! * a collection of properties and *Parts* -//! * **Parts** +//! * **[Parts](cmn/trait.Part.html)** //! * a collection of properties //! * never directly used in *Activities* -//! * **Activities** +//! * **[Activities](cmn/trait.MethodBuilder.html)** //! * operations to apply to *Resources* //! //! Generally speaking, you can invoke *Activities* like this: @@ -74,7 +76,6 @@ //! extern crate "yup-oauth2" as oauth2; //! extern crate "rustc-serialize" as rustc_serialize; //! extern crate youtube3; -//! //! # #[test] fn egal() { //! use std::default::Default; //! use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; @@ -91,9 +92,21 @@ //! hyper::Client::new(), //! ::default(), None); //! let mut hub = YouTube::new(hyper::Client::new(), auth); +//! // You can configure optional parameters by calling the respective setters at will, and +//! // execute the final call using `doit()`. +//! // Values shown here are possibly random and not representative ! +//! let result = hub.live_broadcasts().list("part") +//! .page_token("justo") +//! .on_behalf_of_content_owner_channel("amet.") +//! .on_behalf_of_content_owner("erat") +//! .mine(true) +//! .max_results(92) +//! .id("nonumy") +//! .broadcast_status("dolores") +//! .doit(); +//! // TODO: show how to handle the result ! //! # } //! ``` -//! //! **TODO** Example calls - there should soon be a generator able to do that with proper inputs //! //! ## Handling Errors @@ -133,7 +146,7 @@ extern crate "yup-oauth2" as oauth2; extern crate mime; extern crate url; -mod cmn; +pub mod cmn; use std::collections::HashMap; use std::marker::PhantomData; @@ -144,7 +157,7 @@ use std::collections::BTreeMap; use std::io; use std::fs; -pub use cmn::{Hub, ReadSeek, Part, ResponseResult, RequestValue, NestedType, Delegate, DefaultDelegate}; +use cmn::{Hub, ReadSeek, Part, ResponseResult, RequestValue, NestedType, Delegate, DefaultDelegate}; // ############## @@ -221,7 +234,6 @@ impl Default for Scope { /// extern crate "yup-oauth2" as oauth2; /// extern crate "rustc-serialize" as rustc_serialize; /// extern crate youtube3; -/// /// # #[test] fn egal() { /// use std::default::Default; /// use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage}; @@ -238,9 +250,21 @@ impl Default for Scope { /// hyper::Client::new(), /// ::default(), None); /// let mut hub = YouTube::new(hyper::Client::new(), auth); +/// // You can configure optional parameters by calling the respective setters at will, and +/// // execute the final call using `doit()`. +/// // Values shown here are possibly random and not representative ! +/// let result = hub.live_broadcasts().list("part") +/// .page_token("sadipscing") +/// .on_behalf_of_content_owner_channel("aliquyam") +/// .on_behalf_of_content_owner("ea") +/// .mine(false) +/// .max_results(80) +/// .id("justo") +/// .broadcast_status("et") +/// .doit(); +/// // TODO: show how to handle the result ! /// # } /// ``` -/// pub struct YouTube { client: RefCell, auth: RefCell, @@ -6632,7 +6656,7 @@ impl<'a, C, NC, A> ActivityMethodsBuilder<'a, C, NC, A> { /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.i18n_languages().list("part") -/// .hl("sit") +/// .hl("diam") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -6800,7 +6824,7 @@ impl<'a, C, NC, A> I18nLanguageListMethodBuilder<'a, C, NC, A> where NC: hyper:: /// // execute the final call using `upload(...)`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channel_banners().insert(&req) -/// .on_behalf_of_content_owner("Stet") +/// .on_behalf_of_content_owner("ipsum") /// .upload(fs::File::open("file.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()); /// // TODO: show how to handle the result ! /// # } @@ -6996,9 +7020,9 @@ impl<'a, C, NC, A> ChannelBannerInsertMethodBuilder<'a, C, NC, A> where NC: hype /// // Values shown here are possibly random and not representative ! /// let result = hub.channel_sections().list("part") /// .on_behalf_of_content_owner("et") -/// .mine(true) -/// .id("kasd") -/// .channel_id("accusam") +/// .mine(false) +/// .id("aliquyam") +/// .channel_id("sea") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -7216,8 +7240,8 @@ impl<'a, C, NC, A> ChannelSectionListMethodBuilder<'a, C, NC, A> where NC: hyper /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channel_sections().insert(&req) -/// .on_behalf_of_content_owner_channel("takimata") -/// .on_behalf_of_content_owner("justo") +/// .on_behalf_of_content_owner_channel("Lorem") +/// .on_behalf_of_content_owner("eos") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -7415,7 +7439,7 @@ impl<'a, C, NC, A> ChannelSectionInsertMethodBuilder<'a, C, NC, A> where NC: hyp /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channel_sections().delete("id") -/// .on_behalf_of_content_owner("erat") +/// .on_behalf_of_content_owner("sadipscing") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -7589,7 +7613,7 @@ impl<'a, C, NC, A> ChannelSectionDeleteMethodBuilder<'a, C, NC, A> where NC: hyp /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channel_sections().update(&req) -/// .on_behalf_of_content_owner("labore") +/// .on_behalf_of_content_owner("dolor") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -7784,9 +7808,9 @@ impl<'a, C, NC, A> ChannelSectionUpdateMethodBuilder<'a, C, NC, A> where NC: hyp /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.guide_categories().list("part") -/// .region_code("nonumy") -/// .id("dolores") -/// .hl("gubergren") +/// .region_code("elitr") +/// .id("amet") +/// .hl("no") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -7989,8 +8013,8 @@ impl<'a, C, NC, A> GuideCategoryListMethodBuilder<'a, C, NC, A> where NC: hyper: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlists().insert(&req) -/// .on_behalf_of_content_owner_channel("sadipscing") -/// .on_behalf_of_content_owner("aliquyam") +/// .on_behalf_of_content_owner_channel("labore") +/// .on_behalf_of_content_owner("eirmod") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -8203,13 +8227,13 @@ impl<'a, C, NC, A> PlaylistInsertMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlists().list("part") -/// .page_token("no") -/// .on_behalf_of_content_owner_channel("justo") -/// .on_behalf_of_content_owner("justo") -/// .mine(true) -/// .max_results(84) -/// .id("diam") -/// .channel_id("ipsum") +/// .page_token("invidunt") +/// .on_behalf_of_content_owner_channel("aliquyam") +/// .on_behalf_of_content_owner("accusam") +/// .mine(false) +/// .max_results(92) +/// .id("et") +/// .channel_id("duo") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -8448,7 +8472,7 @@ impl<'a, C, NC, A> PlaylistListMethodBuilder<'a, C, NC, A> where NC: hyper::net: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlists().delete("id") -/// .on_behalf_of_content_owner("et") +/// .on_behalf_of_content_owner("eirmod") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -8622,7 +8646,7 @@ impl<'a, C, NC, A> PlaylistDeleteMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlists().update(&req) -/// .on_behalf_of_content_owner("duo") +/// .on_behalf_of_content_owner("sanctus") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -8807,7 +8831,7 @@ impl<'a, C, NC, A> PlaylistUpdateMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// // execute the final call using `upload(...)`. /// // Values shown here are possibly random and not representative ! /// let result = hub.thumbnails().set("videoId") -/// .on_behalf_of_content_owner("sea") +/// .on_behalf_of_content_owner("amet") /// .upload(fs::File::open("file.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()); /// // TODO: show how to handle the result ! /// # } @@ -9012,16 +9036,16 @@ impl<'a, C, NC, A> ThumbnailSetMethodBuilder<'a, C, NC, A> where NC: hyper::net: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().list("part") -/// .video_category_id("eos") -/// .region_code("erat") -/// .page_token("sadipscing") -/// .on_behalf_of_content_owner("dolor") -/// .my_rating("eirmod") -/// .max_results(58) -/// .locale("amet") -/// .id("no") -/// .hl("labore") -/// .chart("eirmod") +/// .video_category_id("consetetur") +/// .region_code("ut") +/// .page_token("ea") +/// .on_behalf_of_content_owner("sed") +/// .my_rating("dolor") +/// .max_results(53) +/// .locale("dolor") +/// .id("et") +/// .hl("consetetur") +/// .chart("amet.") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -9305,7 +9329,7 @@ impl<'a, C, NC, A> VideoListMethodBuilder<'a, C, NC, A> where NC: hyper::net::Ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().rate("id", "rating") -/// .on_behalf_of_content_owner("aliquyam") +/// .on_behalf_of_content_owner("gubergren") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -9471,7 +9495,7 @@ impl<'a, C, NC, A> VideoRateMethodBuilder<'a, C, NC, A> where NC: hyper::net::Ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().get_rating("id") -/// .on_behalf_of_content_owner("Lorem") +/// .on_behalf_of_content_owner("sit") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -9625,7 +9649,7 @@ impl<'a, C, NC, A> VideoGetRatingMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().delete("id") -/// .on_behalf_of_content_owner("et") +/// .on_behalf_of_content_owner("diam") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -9809,17 +9833,17 @@ impl<'a, C, NC, A> VideoDeleteMethodBuilder<'a, C, NC, A> where NC: hyper::net:: /// req.player = Default::default(); // is VideoPlayer /// req.localizations = Default::default(); // is HashMap /// req.live_streaming_details = Default::default(); // is VideoLiveStreamingDetails -/// req.processing_details = Default::default(); // is VideoProcessingDetails +/// req.snippet = Default::default(); // is VideoSnippet /// req.statistics = Default::default(); // is VideoStatistics +/// req.processing_details = Default::default(); // is VideoProcessingDetails /// req.content_details = Default::default(); // is VideoContentDetails -/// req.snippet = Default::default(); // is VideoSnippet /// req.recording_details = Default::default(); // is VideoRecordingDetails /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().update(&req) -/// .on_behalf_of_content_owner("duo") +/// .on_behalf_of_content_owner("rebum.") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -10057,10 +10081,10 @@ impl<'a, C, NC, A> VideoUpdateMethodBuilder<'a, C, NC, A> where NC: hyper::net:: /// req.player = Default::default(); // is VideoPlayer /// req.localizations = Default::default(); // is HashMap /// req.live_streaming_details = Default::default(); // is VideoLiveStreamingDetails -/// req.processing_details = Default::default(); // is VideoProcessingDetails +/// req.snippet = Default::default(); // is VideoSnippet /// req.statistics = Default::default(); // is VideoStatistics +/// req.processing_details = Default::default(); // is VideoProcessingDetails /// req.content_details = Default::default(); // is VideoContentDetails -/// req.snippet = Default::default(); // is VideoSnippet /// req.recording_details = Default::default(); // is VideoRecordingDetails /// /// // You can configure optional parameters by calling the respective setters at will, and @@ -10068,10 +10092,10 @@ impl<'a, C, NC, A> VideoUpdateMethodBuilder<'a, C, NC, A> where NC: hyper::net:: /// // Values shown here are possibly random and not representative ! /// let result = hub.videos().insert(&req) /// .stabilize(true) -/// .on_behalf_of_content_owner_channel("eirmod") -/// .on_behalf_of_content_owner("sanctus") -/// .notify_subscribers(true) -/// .auto_levels(true) +/// .on_behalf_of_content_owner_channel("sadipscing") +/// .on_behalf_of_content_owner("vero") +/// .notify_subscribers(false) +/// .auto_levels(false) /// .upload_resumable(fs::File::open("file.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()); /// // TODO: show how to handle the result ! /// # } @@ -10555,16 +10579,16 @@ impl<'a, C, NC, A> SubscriptionInsertMethodBuilder<'a, C, NC, A> where NC: hyper /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.subscriptions().list("part") -/// .page_token("consetetur") -/// .order("ut") -/// .on_behalf_of_content_owner_channel("ea") -/// .on_behalf_of_content_owner("sed") +/// .page_token("dolore") +/// .order("duo") +/// .on_behalf_of_content_owner_channel("aliquyam") +/// .on_behalf_of_content_owner("Lorem") /// .my_subscribers(true) /// .mine(true) -/// .max_results(53) -/// .id("et") -/// .for_channel_id("consetetur") -/// .channel_id("amet.") +/// .max_results(56) +/// .id("takimata") +/// .for_channel_id("nonumy") +/// .channel_id("kasd") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -10990,35 +11014,35 @@ impl<'a, C, NC, A> SubscriptionDeleteMethodBuilder<'a, C, NC, A> where NC: hyper /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.search().list("part") -/// .video_type("gubergren") -/// .video_syndicated("justo") -/// .video_license("sit") -/// .video_embeddable("vero") -/// .video_duration("diam") +/// .video_type("At") +/// .video_syndicated("labore") +/// .video_license("invidunt") +/// .video_embeddable("ea") +/// .video_duration("sadipscing") /// .video_dimension("rebum.") -/// .video_definition("consetetur") -/// .video_category_id("sadipscing") -/// .video_caption("vero") -/// .type_("sadipscing") -/// .topic_id("invidunt") -/// .safe_search("consetetur") -/// .relevance_language("dolore") -/// .related_to_video_id("duo") -/// .region_code("aliquyam") -/// .q("Lorem") -/// .published_before("et") -/// .published_after("clita") -/// .page_token("consetetur") -/// .order("takimata") -/// .on_behalf_of_content_owner("nonumy") -/// .max_results(88) -/// .location_radius("sanctus") -/// .location("takimata") -/// .for_mine(true) +/// .video_definition("dolore") +/// .video_category_id("nonumy") +/// .video_caption("sed") +/// .type_("aliquyam") +/// .topic_id("sit") +/// .safe_search("eirmod") +/// .relevance_language("consetetur") +/// .related_to_video_id("labore") +/// .region_code("sed") +/// .q("ea") +/// .published_before("gubergren") +/// .published_after("aliquyam") +/// .page_token("eos") +/// .order("tempor") +/// .on_behalf_of_content_owner("sea") +/// .max_results(16) +/// .location_radius("ipsum") +/// .location("aliquyam") +/// .for_mine(false) /// .for_content_owner(false) -/// .event_type("invidunt") -/// .channel_type("ea") -/// .channel_id("sadipscing") +/// .event_type("diam") +/// .channel_type("ut") +/// .channel_id("justo") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -11530,7 +11554,7 @@ impl<'a, C, NC, A> SearchListMethodBuilder<'a, C, NC, A> where NC: hyper::net::N /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.i18n_regions().list("part") -/// .hl("dolore") +/// .hl("amet") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -11702,14 +11726,14 @@ impl<'a, C, NC, A> I18nRegionListMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// req.status = Default::default(); // is LiveStreamStatus /// req.snippet = Default::default(); // is LiveStreamSnippet /// req.cdn = Default::default(); // is CdnSettings -/// req.id = Some("nonumy".to_string()); +/// req.id = Some("accusam".to_string()); /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_streams().update(&req) -/// .on_behalf_of_content_owner_channel("sed") -/// .on_behalf_of_content_owner("aliquyam") +/// .on_behalf_of_content_owner_channel("clita") +/// .on_behalf_of_content_owner("diam") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -11913,8 +11937,8 @@ impl<'a, C, NC, A> LiveStreamUpdateMethodBuilder<'a, C, NC, A> where NC: hyper:: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_streams().delete("id") -/// .on_behalf_of_content_owner_channel("eirmod") -/// .on_behalf_of_content_owner("consetetur") +/// .on_behalf_of_content_owner_channel("est") +/// .on_behalf_of_content_owner("clita") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -12098,12 +12122,12 @@ impl<'a, C, NC, A> LiveStreamDeleteMethodBuilder<'a, C, NC, A> where NC: hyper:: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_streams().list("part") -/// .page_token("sed") -/// .on_behalf_of_content_owner_channel("ea") -/// .on_behalf_of_content_owner("gubergren") +/// .page_token("ut") +/// .on_behalf_of_content_owner_channel("dolores") +/// .on_behalf_of_content_owner("eos") /// .mine(false) -/// .max_results(77) -/// .id("tempor") +/// .max_results(82) +/// .id("sed") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -12343,14 +12367,14 @@ impl<'a, C, NC, A> LiveStreamListMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// req.status = Default::default(); // is LiveStreamStatus /// req.snippet = Default::default(); // is LiveStreamSnippet /// req.cdn = Default::default(); // is CdnSettings -/// req.id = Some("sea".to_string()); +/// req.id = Some("aliquyam".to_string()); /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_streams().insert(&req) -/// .on_behalf_of_content_owner_channel("labore") -/// .on_behalf_of_content_owner("ipsum") +/// .on_behalf_of_content_owner_channel("ea") +/// .on_behalf_of_content_owner("ea") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -12566,13 +12590,13 @@ impl<'a, C, NC, A> LiveStreamInsertMethodBuilder<'a, C, NC, A> where NC: hyper:: /// // Values shown here are possibly random and not representative ! /// let mut req: Channel = Default::default(); /// req.invideo_promotion = Default::default(); // is InvideoPromotion -/// req.id = Some("aliquyam".to_string()); +/// req.id = Some("et".to_string()); /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channels().update(&req) -/// .on_behalf_of_content_owner("dolores") +/// .on_behalf_of_content_owner("dolor") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -12772,15 +12796,15 @@ impl<'a, C, NC, A> ChannelUpdateMethodBuilder<'a, C, NC, A> where NC: hyper::net /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.channels().list("part") -/// .page_token("diam") -/// .on_behalf_of_content_owner("ut") -/// .my_subscribers(false) +/// .page_token("kasd") +/// .on_behalf_of_content_owner("invidunt") +/// .my_subscribers(true) /// .mine(true) -/// .max_results(55) +/// .max_results(38) /// .managed_by_me(true) -/// .id("clita") -/// .for_username("diam") -/// .category_id("justo") +/// .id("eirmod") +/// .for_username("At") +/// .category_id("consetetur") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -13193,12 +13217,12 @@ impl<'a, C, NC, A> PlaylistItemDeleteMethodBuilder<'a, C, NC, A> where NC: hyper /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlist_items().list("part") -/// .video_id("invidunt") -/// .playlist_id("ut") -/// .page_token("dolores") -/// .on_behalf_of_content_owner("eos") -/// .max_results(23) -/// .id("duo") +/// .video_id("sit") +/// .playlist_id("takimata") +/// .page_token("elitr") +/// .on_behalf_of_content_owner("nonumy") +/// .max_results(86) +/// .id("Lorem") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -13443,7 +13467,7 @@ impl<'a, C, NC, A> PlaylistItemListMethodBuilder<'a, C, NC, A> where NC: hyper:: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.playlist_items().insert(&req) -/// .on_behalf_of_content_owner("sed") +/// .on_behalf_of_content_owner("Lorem") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -13827,7 +13851,7 @@ impl<'a, C, NC, A> PlaylistItemUpdateMethodBuilder<'a, C, NC, A> where NC: hyper /// // execute the final call using `upload(...)`. /// // Values shown here are possibly random and not representative ! /// let result = hub.watermarks().set(&req, "channelId") -/// .on_behalf_of_content_owner("ea") +/// .on_behalf_of_content_owner("ut") /// .upload(fs::File::open("file.ext").unwrap(), 282, "application/octet-stream".parse().unwrap()); /// // TODO: show how to handle the result ! /// # } @@ -14018,7 +14042,7 @@ impl<'a, C, NC, A> WatermarkSetMethodBuilder<'a, C, NC, A> where NC: hyper::net: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.watermarks().unset("channelId") -/// .on_behalf_of_content_owner("et") +/// .on_behalf_of_content_owner("amet.") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -14181,11 +14205,11 @@ impl<'a, C, NC, A> WatermarkUnsetMethodBuilder<'a, C, NC, A> where NC: hyper::ne /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().control("id", "part") -/// .walltime("kasd") -/// .on_behalf_of_content_owner_channel("invidunt") -/// .on_behalf_of_content_owner("rebum.") -/// .offset_time_ms("Lorem") -/// .display_slate(false) +/// .walltime("dolor") +/// .on_behalf_of_content_owner_channel("sea") +/// .on_behalf_of_content_owner("ut") +/// .offset_time_ms("eirmod") +/// .display_slate(true) /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -14429,14 +14453,14 @@ impl<'a, C, NC, A> LiveBroadcastControlMethodBuilder<'a, C, NC, A> where NC: hyp /// req.status = Default::default(); // is LiveBroadcastStatus /// req.snippet = Default::default(); // is LiveBroadcastSnippet /// req.content_details = Default::default(); // is LiveBroadcastContentDetails -/// req.id = Some("invidunt".to_string()); +/// req.id = Some("voluptua.".to_string()); /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().update(&req) -/// .on_behalf_of_content_owner_channel("eirmod") -/// .on_behalf_of_content_owner("At") +/// .on_behalf_of_content_owner_channel("dolor") +/// .on_behalf_of_content_owner("et") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -14655,14 +14679,14 @@ impl<'a, C, NC, A> LiveBroadcastUpdateMethodBuilder<'a, C, NC, A> where NC: hype /// req.status = Default::default(); // is LiveBroadcastStatus /// req.snippet = Default::default(); // is LiveBroadcastSnippet /// req.content_details = Default::default(); // is LiveBroadcastContentDetails -/// req.id = Some("consetetur".to_string()); +/// req.id = Some("et".to_string()); /// /// // You can configure optional parameters by calling the respective setters at will, and /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().insert(&req) -/// .on_behalf_of_content_owner_channel("et") -/// .on_behalf_of_content_owner("sed") +/// .on_behalf_of_content_owner_channel("vero") +/// .on_behalf_of_content_owner("ut") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -14875,9 +14899,9 @@ impl<'a, C, NC, A> LiveBroadcastInsertMethodBuilder<'a, C, NC, A> where NC: hype /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().bind("id", "part") -/// .stream_id("elitr") -/// .on_behalf_of_content_owner_channel("nonumy") -/// .on_behalf_of_content_owner("rebum.") +/// .stream_id("ipsum") +/// .on_behalf_of_content_owner_channel("justo") +/// .on_behalf_of_content_owner("dolore") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -15092,13 +15116,13 @@ impl<'a, C, NC, A> LiveBroadcastBindMethodBuilder<'a, C, NC, A> where NC: hyper: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().list("part") -/// .page_token("Lorem") -/// .on_behalf_of_content_owner_channel("diam") -/// .on_behalf_of_content_owner("ut") -/// .mine(true) -/// .max_results(50) -/// .id("ipsum") -/// .broadcast_status("ut") +/// .page_token("dolor") +/// .on_behalf_of_content_owner_channel("takimata") +/// .on_behalf_of_content_owner("et") +/// .mine(false) +/// .max_results(17) +/// .id("sed") +/// .broadcast_status("no") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -15335,8 +15359,8 @@ impl<'a, C, NC, A> LiveBroadcastListMethodBuilder<'a, C, NC, A> where NC: hyper: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().delete("id") -/// .on_behalf_of_content_owner_channel("sea") -/// .on_behalf_of_content_owner("ut") +/// .on_behalf_of_content_owner_channel("rebum.") +/// .on_behalf_of_content_owner("labore") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -15517,8 +15541,8 @@ impl<'a, C, NC, A> LiveBroadcastDeleteMethodBuilder<'a, C, NC, A> where NC: hype /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.live_broadcasts().transition("broadcastStatus", "id", "part") -/// .on_behalf_of_content_owner_channel("dolor") -/// .on_behalf_of_content_owner("et") +/// .on_behalf_of_content_owner_channel("sea") +/// .on_behalf_of_content_owner("elitr") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -15732,9 +15756,9 @@ impl<'a, C, NC, A> LiveBroadcastTransitionMethodBuilder<'a, C, NC, A> where NC: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.video_categories().list("part") -/// .region_code("vero") -/// .id("ut") -/// .hl("sed") +/// .region_code("sea") +/// .id("consetetur") +/// .hl("diam") /// .doit(); /// // TODO: show how to handle the result ! /// # } @@ -15928,14 +15952,14 @@ impl<'a, C, NC, A> VideoCategoryListMethodBuilder<'a, C, NC, A> where NC: hyper: /// // execute the final call using `doit()`. /// // Values shown here are possibly random and not representative ! /// let result = hub.activities().list("part") -/// .region_code("ipsum") -/// .published_before("justo") -/// .published_after("dolore") -/// .page_token("vero") +/// .region_code("dolores") +/// .published_before("consetetur") +/// .published_after("dolor") +/// .page_token("aliquyam") /// .mine(false) -/// .max_results(43) +/// .max_results(85) /// .home(true) -/// .channel_id("nonumy") +/// .channel_id("Stet") /// .doit(); /// // TODO: show how to handle the result ! /// # } diff --git a/src/mako/lib.rs.mako b/src/mako/lib.rs.mako index d3bb9155c51..69869edaa7f 100644 --- a/src/mako/lib.rs.mako +++ b/src/mako/lib.rs.mako @@ -6,7 +6,7 @@ <% from util import (new_context, rust_comment, rust_doc_comment, rust_module_doc_comment, rb_type, hub_type, mangle_ident, hub_type_params_s, - hub_type_bounds, rb_type_params_s) + hub_type_bounds, rb_type_params_s, find_fattest_resource) c = new_context(schemas, resources) hub_type = hub_type(c.schemas, util.canonical_name()) @@ -34,7 +34,7 @@ extern crate "yup-oauth2" as oauth2; extern crate mime; extern crate url; -mod cmn; +pub mod cmn; use std::collections::HashMap; use std::marker::PhantomData; @@ -45,7 +45,7 @@ use std::collections::BTreeMap; use std::io; use std::fs; -pub use cmn::{Hub, ReadSeek, Part, ResponseResult, RequestValue, NestedType, Delegate, DefaultDelegate}; +use cmn::{Hub, ReadSeek, Part, ResponseResult, RequestValue, NestedType, Delegate, DefaultDelegate}; // ############## @@ -80,7 +80,7 @@ ${lib.scope_enum()} /// Instantiate a new hub /// <%block filter="rust_doc_comment">\ -<%lib:hub_usage_example/>\ +${lib.hub_usage_example(c)}\ pub struct ${hub_type}${ht_params} { client: RefCell, diff --git a/src/mako/lib/lib.mako b/src/mako/lib/lib.mako index a21ad50c576..1c73a283bcb 100644 --- a/src/mako/lib/lib.mako +++ b/src/mako/lib/lib.mako @@ -1,7 +1,10 @@ -<%! from util import (activity_split, put_and, md_italic, split_camelcase_s, canonical_type_name, +<%! from util import (activity_split, put_and, md_italic, split_camelcase_s, canonical_type_name, hub_type, rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block, - unindent_first_by, mangle_ident, mb_type, singular, scope_url_to_variant) %>\ + unindent_first_by, mangle_ident, mb_type, singular, scope_url_to_variant, + PART_MARKER_TRAIT, RESOURCE_MARKER_TRAIT, METHOD_BUILDER_MARKERT_TRAIT, + find_fattest_resource, build_all_params, pass_through, parts_from_params) %>\ <%namespace name="util" file="util.mako"/>\ +<%namespace name="mbuild" file="mbuild.mako"/>\ ## If rust-doc is True, examples will be made to work for rust doc tests. Otherwise they are set ## for github markdown. @@ -10,28 +13,21 @@ <%def name="docs(c, rust_doc=True)">\ <% # fr == fattest resource, the fatter, the more important, right ? - fr = None - if schemas: - for candidate in sorted(schemas.values(), key=lambda s: (len(c.sta_map.get(s.id, [])), len(s.get('properties', []))), reverse=True): - if candidate.id in c.sta_map: - fr = candidate - break - # end for each candidate to check + fr = find_fattest_resource(c) + hub_url = 'struct.' + hub_type(c.schemas, util.canonical_name()) + '.html' %>\ # Features -Handle the following *Resources* with ease ... +Handle the following *Resources* with ease from the central [hub](${hub_url}) ... % for r in sorted(c.rta_map.keys()): <% md_methods = list() + doc_base_url = '' + if not rust_doc: + doc_base_url = cargo.doc_base_url + '/' + util.library_name() + '/' for method in sorted(c.rta_map[r]): - if rust_doc: - md_methods.append("[*%s*](struct.%s.html)" % (' '.join(n.lower() for n in reversed(method.split('.'))), mb_type(r, method))) - else: - # TODO: link to final destination, possibly just have one for all ... - md_methods.append("*%s*" % method) - + md_methods.append("[*%s*](%sstruct.%s.html)" % (' '.join(n.lower() for n in reversed(method.split('.'))), doc_base_url, mb_type(r, method))) md_resource = split_camelcase_s(r) sn = singular(canonical_type_name(r)) @@ -45,20 +41,24 @@ Handle the following *Resources* with ease ... Everything else about the *${util.canonical_name()}* API can be found at the [official documentation site](${documentationLink}). % endif +% if rust_doc: + +Not what you are looking for ? Find all other google APIs in their Rust [documentation index](../index.html). +% endif # Structure of this Library The API is structured into the following primary items: -* **Hub** +* **[Hub](${hub_url})** * a central object to maintain state and allow accessing all *Activities* -* **Resources** +* **[Resources](cmn/trait.${RESOURCE_MARKER_TRAIT}.html)** * primary types that you can apply *Activities* to * a collection of properties and *Parts* - * **Parts** + * **[Parts](cmn/trait.${PART_MARKER_TRAIT}.html)** * a collection of properties * never directly used in *Activities* -* **Activities** +* **[Activities](cmn/trait.${METHOD_BUILDER_MARKERT_TRAIT}.html)** * operations to apply to *Resources* Generally speaking, you can invoke *Activities* like this: @@ -87,7 +87,7 @@ The `${api.terms.action}()` method performs the actual communication with the se ${'##'} Instantiating the Hub -${self.hub_usage_example(rust_doc)}\ +${self.hub_usage_example(c, rust_doc, fr=fr)}\ **TODO** Example calls - there should soon be a generator able to do that with proper inputs @@ -142,21 +142,43 @@ let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\ ## You will still have to set the filter for your comment type - either nothing, or rust_doc_comment ! ############################################################################################### ############################################################################################### -<%def name="hub_usage_example(rust_doc=True)">\ +<%def name="hub_usage_example(c, rust_doc=True, fr=None)">\ <% test_filter = rust_test_fn_invisible main_filter = rust_doc_test_norun if not rust_doc: - test_filter = lambda s: s + test_filter = pass_through main_filter = markdown_rust_block + + if fr is None: + fr = find_fattest_resource(c) + if fr is not None: + fqan = None + last_param_count = None + for fqan in c.sta_map[fr.id]: + _, aresource, amethod = activity_split(fqan) + am = c.fqan_map[fqan] + build_all_params(c, am) + aparams, arequest_value = build_all_params(c, am) + + if last_param_count is None or len(aparams) > last_param_count: + m, resource, method, params, request_value = am, aresource, amethod, aparams, arequest_value + last_param_count = len(aparams) + # end for each fn to test + part_prop, parts = parts_from_params(params) + # end fill in values %>\ +% if fr: +${mbuild.usage(resource, method, m, params, request_value, parts, show_all=True, rust_doc=rust_doc)}\ +% else: <%block filter="main_filter">\ ${util.test_prelude()}\ <%block filter="test_filter">\ -${self.test_hub(canonical_type_name(util.canonical_name()))}\ +${self.test_hub(hub_type(c.schemas, util.canonical_name()))} +% endif ############################################################################################### diff --git a/src/mako/lib/mbuild.mako b/src/mako/lib/mbuild.mako index 97e80386a97..33349670113 100644 --- a/src/mako/lib/mbuild.mako +++ b/src/mako/lib/mbuild.mako @@ -6,7 +6,8 @@ schema_to_required_property, rust_copy_value_s, is_required_property, hide_rust_doc_test, build_all_params, REQUEST_VALUE_PROPERTY_NAME, organize_params, indent_by, to_rust_type, rnd_arg_val_for_type, extract_parts, mb_type_params_s, - hub_type_params_s, method_media_params, enclose_in, mb_type_bounds, method_response) + hub_type_params_s, method_media_params, enclose_in, mb_type_bounds, method_response, + METHOD_BUILDER_MARKERT_TRAIT, pass_through, markdown_rust_block, parts_from_params) def get_parts(part_prop): if not part_prop: @@ -37,13 +38,9 @@ mb_tparams = mb_type_params_s(m) ThisType = mb_type(resource, method) + mb_tparams - params, request_value = build_all_params(schemas, c, m, IO_REQUEST, REQUEST_VALUE_PROPERTY_NAME) - part_prop = None - for p in params: - if p.name == 'part': - part_prop = p - break - # end for each param + params, request_value = build_all_params(c, m) + + part_prop, parts = parts_from_params(params) part_desc = make_parts_desc(part_prop) parts = get_parts(part_prop) %>\ @@ -103,11 +100,11 @@ pub struct ${ThisType} % endif } -impl${mb_tparams} cmn::MethodBuilder for ${ThisType} {} +impl${mb_tparams} cmn::${METHOD_BUILDER_MARKERT_TRAIT} for ${ThisType} {} impl${mb_tparams} ${ThisType} where ${', '.join(mb_type_bounds())} { -${self._action_fn(resource, method, m, params, request_value, parts)}\ +${self._action_fn(c, resource, method, m, params, request_value, parts)}\ ## SETTERS ############### % for p in params: @@ -208,9 +205,11 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\ ## creates usage docs the method builder +## show_all: If True, we will show all comments and hide no prelude. It's good to build a complete, +## documented example for a given method. ############################################################################################### ############################################################################################### -<%def name="usage(resource, method, m, params, request_value, parts)">\ +<%def name="usage(resource, method, m, params, request_value, parts=None, show_all=False, rust_doc=True)">\ <% hub_type_name = hub_type(schemas, util.canonical_name()) required_props, optional_props, part_prop = organize_params(params, request_value) @@ -250,24 +249,28 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\ action_args = media_params and media_params[-1].type.example_value or '' random_value_warning = "Values shown here are possibly random and not representative !" + + hide_filter = show_all and pass_through or hide_rust_doc_test + test_block_filter = rust_doc and rust_doc_test_norun or markdown_rust_block + test_fn_filter = rust_doc and rust_test_fn_invisible or pass_through %>\ -<%block filter="rust_doc_test_norun">\ -${capture(util.test_prelude) | hide_rust_doc_test}\ +<%block filter="test_block_filter">\ +${capture(util.test_prelude) | hide_filter}\ % if request_value: # use ${util.library_name()}::${request_value.id}; % endif % if media_params: # use std::fs; % endif -<%block filter="rust_test_fn_invisible">\ -${capture(lib.test_hub, hub_type_name, comments=False) | hide_rust_doc_test} +<%block filter="test_fn_filter">\ +${capture(lib.test_hub, hub_type_name, comments=show_all) | hide_filter} % if request_value: // As the method needs a request, you would usually fill it with the desired information // into the respective structure. Some of the parts shown here might not be applicable ! // ${random_value_warning} let mut ${rb_name}: ${request_value.id} = Default::default(); % for spn, sp in request_value.get('properties', dict()).iteritems(): -% if spn not in parts: +% if parts is not None and spn not in parts: <% continue %> % endif <% @@ -312,7 +315,7 @@ ${'.' + action_name | indent_by(13)}(${action_args}); ## create an entire 'api.terms.action' method ############################################################################################### ############################################################################################### -<%def name="_action_fn(resource, method, m, params, request_value, parts)">\ +<%def name="_action_fn(c, resource, method, m, params, request_value, parts)">\ <% import os.path join_url = lambda b, e: b.strip('/') + e @@ -323,7 +326,7 @@ ${'.' + action_name | indent_by(13)}(${action_args}); qualifier = 'pub ' add_args = '' rtype = 'cmn::Result<()>' - response_schema = method_response(schemas, c, m) + response_schema = method_response(c, m) if response_schema: rtype = 'cmn::Result<%s>' % (response_schema.id) diff --git a/src/mako/lib/rbuild.mako b/src/mako/lib/rbuild.mako index b9caacad14b..ce8d9172b04 100644 --- a/src/mako/lib/rbuild.mako +++ b/src/mako/lib/rbuild.mako @@ -56,7 +56,7 @@ impl${rb_params} ${ThisType} { # skip part if we have a request resource. Only resources can have parts # that we can easily deduce - params, request_value = build_all_params(schemas, c, m, IO_REQUEST, REQUEST_VALUE_PROPERTY_NAME) + params, request_value = build_all_params(c, m) required_props, optional_props, part_prop = organize_params(params, request_value) method_args = '' diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index 83925a890d7..64e28561944 100644 --- a/src/mako/lib/util.py +++ b/src/mako/lib/util.py @@ -56,6 +56,8 @@ REQUEST_PRIORITY = 100 REQUEST_MARKER_TRAIT = 'RequestValue' RESPONSE_MARKER_TRAIT = 'ResponseResult' +RESOURCE_MARKER_TRAIT = 'Resource' +METHOD_BUILDER_MARKERT_TRAIT = 'MethodBuilder' PART_MARKER_TRAIT = 'Part' NESTED_MARKER_TRAIT = 'NestedType' REQUEST_VALUE_PROPERTY_NAME = 'request' @@ -126,6 +128,10 @@ def hide_rust_doc_test(s): def unindent(s): return re_first_4_spaces.sub('', s) +# don't do anything with the passed in string +def pass_through(s): + return s + # tabs: 1 tabs is 4 spaces def unindent_first_by(tabs): def unindent_inner(s): @@ -377,7 +383,7 @@ def schema_markers(s, c): # it should have at least one activity that matches it's type to qualify for the Resource trait for fqan, iot in activities.iteritems(): if activity_name_to_type_name(activity_split(fqan)[1]).lower() == sid.lower(): - res.add('cmn::Resource') + res.add('cmn::%s' % RESOURCE_MARKER_TRAIT) if IO_RESPONSE in iot: res.add(RESPONSE_MARKER_TRAIT) if IO_REQUEST in iot: @@ -444,8 +450,8 @@ def method_params(m, required=None, location=None): # end for each parameter return sorted(res, key=lambda p: (p.priority, p.name), reverse=True) -def _method_io(type_name, schemas, c, m, marker=None): - s = schemas.get(m.get(type_name, dict()).get(TREF)) +def _method_io(type_name, c, m, marker=None): + s = c.schemas.get(m.get(type_name, dict()).get(TREF)) if s is None: return s if s and marker and marker not in schema_markers(s, c): @@ -454,12 +460,12 @@ def _method_io(type_name, schemas, c, m, marker=None): # return the given method's request or response schema (dict), or None. # optionally return only schemas with the given marker trait -def method_request(schemas, c, m, marker=None): - return _method_io('request', schemas, c, m, marker) +def method_request(c, m, marker=None): + return _method_io('request', c, m, marker) # As method request, but returns response instead -def method_response(schemas, c, m, marker=None): - return _method_io('response', schemas, c, m, marker) +def method_response(c, m, marker=None): + return _method_io('response', c, m, marker) # return string like 'n.clone()', but depending on the type name of tn (e.g. &str -> n.to_string()) def rust_copy_value_s(n, tn, p): @@ -529,11 +535,11 @@ def method_media_params(m): # Build all parameters used in a given method ! # schemas, context, method(dict), 'request'|'response', request_prop_name -> (params, request_value|None) -def build_all_params(schemas, c, m, n, npn): - request_value = method_request(schemas, c, m) +def build_all_params(c, m): + request_value = method_request(c, m) params = method_params(m) if request_value: - params.insert(0, schema_to_required_property(request_value, npn)) + params.insert(0, schema_to_required_property(request_value, REQUEST_VALUE_PROPERTY_NAME)) # add the delegate. It's a type parameter, which has to remain in sync with the type-parameters we actually build. dp = type(m)({ 'name': 'delegate', TREF: "&'a mut %s" % DELEGATE_TYPE, @@ -748,6 +754,7 @@ def mb_additional_type_params(m): def mb_type(r, m): return "%s%sMethodBuilder" % (singular(canonical_type_name(r)), dot_sep_to_canonical_type_name(m)) +# canonicalName = util.canonical_name() def hub_type(schemas, canonicalName): name = canonical_type_name(canonicalName) if schemas and name in schemas: @@ -772,6 +779,31 @@ def property(n): def dot_sep_to_canonical_type_name(n): return ''.join(canonical_type_name(singular(t)) for t in n.split('.')) +def find_fattest_resource(c): + fr = None + if c.schemas: + for candidate in sorted(c.schemas.values(), + key=lambda s: (len(c.sta_map.get(s.id, [])), len(s.get('properties', []))), reverse=True): + if candidate.id in c.sta_map: + fr = candidate + break + # end for each candidate to check + # end if there are schemas + return fr + +# Extract valid parts from the description of the parts prop contained within the given parameter list +# can be an empty list. +def parts_from_params(params): + part_prop = None + for p in params: + if p.name == 'part': + part_prop = p + break + # end for each param + if part_prop: + return part_prop, extract_parts(part_prop.get('description', '')) + return part_prop, list() + # Convert a scope url to a nice enum variant identifier, ready for use in code # name = name of the api, without version def scope_url_to_variant(name, url, fully_qualified=True):