Skip to content

Commit 615a124

Browse files
ByronByron
committed
feat(hub): generate hub implementation and docs
This includes docs for the library usage. It's totally great to be able to paste example code right were it belongs, and also put the same elsewhere to compose more complex docs.
1 parent 85171ce commit 615a124

9 files changed

Lines changed: 264 additions & 19 deletions

File tree

‎gen/youtube3/README.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,17 +60,42 @@ let r = hub.videos().delete(...).do()
6060
```
6161

6262
The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities`
63-
supports various methods to configure the impending operation. It is made such that all required arguments have to be
63+
supports various methods to configure the impending operation (not shown here). It is made such that all required arguments have to be
6464
specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
6565
The `do()` method performs the actual communication with the server and returns the respective result.
6666

6767
# Usage (*TODO*)
6868

6969
## Instantiating the Hub
7070

71+
```Rust
72+
extern crate hyper;
73+
extern crate "yup-oauth2" as oauth2;
74+
extern crate "rustc-serialize" as rustc_serialize;
75+
extern crate youtube3;
76+
77+
use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
78+
use std::default::Default;
79+
80+
use youtube3::YouTube;
81+
82+
// Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`,
83+
// among other things.
84+
let secret: ApplicationSecret = Default::default();
85+
// Instantiate the authenticator. It will choose a suitable authentication flow for you,
86+
// unless you replace `None` with the desired Flow
87+
// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
88+
// You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
89+
let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
90+
hyper::Client::new(),
91+
<MemoryStorage as Default>::default(), None);
92+
let mut hub = YouTube::new(hyper::Client::new(), auth);
93+
```
94+
95+
**TODO** Example calls - there should soon be a generator able to do that with proper inputs
7196
## About error handling
7297

73-
## About costumization
98+
## About Customization/Callbacks
7499

75100
[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
76101
[google-go-api]: https://github.com/google/google-api-go-client

‎gen/youtube3/src/cmn.rs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22
// DO NOT EDIT
33
use std::marker::MarkerTrait;
44

5+
/// Identifies the Hub. There is only one per library, this trait is supposed
6+
/// to make intended use more explicit.
7+
/// The hub allows to access all resource methods more easily.
8+
pub trait Hub: MarkerTrait {}
9+
510
/// Identifies types which can be inserted and deleted.
611
/// Types with this trait are most commonly used by clients of this API.
712
pub trait Resource: MarkerTrait {}

‎gen/youtube3/src/lib.rs‎

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,17 +57,44 @@
5757
//! ```
5858
//!
5959
//! The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities`
60-
//! supports various methods to configure the impending operation. It is made such that all required arguments have to be
60+
//! supports various methods to configure the impending operation (not shown here). It is made such that all required arguments have to be
6161
//! specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
6262
//! The `do()` method performs the actual communication with the server and returns the respective result.
6363
//!
6464
//! # Usage (*TODO*)
6565
//!
6666
//! ## Instantiating the Hub
6767
//!
68+
//! ```test_harness,no_run
69+
//! extern crate hyper;
70+
//! extern crate "yup-oauth2" as oauth2;
71+
//! extern crate "rustc-serialize" as rustc_serialize;
72+
//! extern crate youtube3;
73+
//!
74+
//! # #[test] fn egal() {
75+
//! use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
76+
//! use std::default::Default;
77+
//!
78+
//! use youtube3::YouTube;
79+
//!
80+
//! // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`,
81+
//! // among other things.
82+
//! let secret: ApplicationSecret = Default::default();
83+
//! // Instantiate the authenticator. It will choose a suitable authentication flow for you,
84+
//! // unless you replace `None` with the desired Flow
85+
//! // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
86+
//! // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
87+
//! let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
88+
//! hyper::Client::new(),
89+
//! <MemoryStorage as Default>::default(), None);
90+
//! let mut hub = YouTube::new(hyper::Client::new(), auth);
91+
//! # }
92+
//! ```
93+
//!
94+
//! **TODO** Example calls - there should soon be a generator able to do that with proper inputs
6895
//! ## About error handling
6996
//!
70-
//! ## About costumization
97+
//! ## About Customization/Callbacks
7198
//!
7299
//! [builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
73100
//! [google-go-api]: https://github.com/google/google-api-go-client
@@ -77,14 +104,77 @@
77104
#![feature(core)]
78105
#![allow(non_snake_case)]
79106

107+
extern crate hyper;
80108
extern crate "rustc-serialize" as rustc_serialize;
81109
extern crate "yup-oauth2" as oauth2;
82110

83111
mod cmn;
84112

85113
use std::collections::HashMap;
114+
use std::marker::PhantomData;
115+
use std::borrow::BorrowMut;
116+
use std::cell::RefCell;
117+
118+
pub use cmn::{Hub, Resource, Part, ResponseResult, RequestResult, NestedType};
119+
120+
// ########
121+
// HUB ###
122+
// ######
123+
124+
/// Central instance to access all YouTube related resource activities
125+
///
126+
/// # Examples
127+
///
128+
/// Instantiate a new hub
129+
///
130+
/// ```test_harness,no_run
131+
/// extern crate hyper;
132+
/// extern crate "yup-oauth2" as oauth2;
133+
/// extern crate "rustc-serialize" as rustc_serialize;
134+
/// extern crate youtube3;
135+
///
136+
/// # #[test] fn egal() {
137+
/// use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
138+
/// use std::default::Default;
139+
///
140+
/// use youtube3::YouTube;
141+
///
142+
/// // Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`,
143+
/// // among other things.
144+
/// let secret: ApplicationSecret = Default::default();
145+
/// // Instantiate the authenticator. It will choose a suitable authentication flow for you,
146+
/// // unless you replace `None` with the desired Flow
147+
/// // Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
148+
/// // You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
149+
/// let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
150+
/// hyper::Client::new(),
151+
/// <MemoryStorage as Default>::default(), None);
152+
/// let mut hub = YouTube::new(hyper::Client::new(), auth);
153+
/// # }
154+
/// ```
155+
///
156+
pub struct YouTube<C, NC, A> {
157+
client: RefCell<C>,
158+
auth: RefCell<A>,
159+
_m: PhantomData<NC>
160+
}
161+
162+
impl<'a, C, NC, A> Hub for YouTube<C, NC, A> {}
163+
164+
impl<'a, C, NC, A> YouTube<C, NC, A>
165+
where NC: hyper::net::NetworkConnector,
166+
C: BorrowMut<hyper::Client<NC>> + 'a,
167+
A: oauth2::GetToken {
168+
169+
pub fn new(client: C, authenticator: A) -> YouTube<C, NC, A> {
170+
YouTube {
171+
client: RefCell::new(client),
172+
auth: RefCell::new(authenticator),
173+
_m: PhantomData,
174+
}
175+
}
176+
}
86177

87-
pub use cmn::{Resource, Part, ResponseResult, RequestResult, NestedType};
88178

89179
// ############
90180
// SCHEMAS ###

‎src/mako/README.md.mako‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,5 @@
99
</%block>
1010
The `${util.library_name()}` library allows access to all features of *${canonicalName}*.
1111

12-
${lib.docs(c)}
12+
${lib.docs(c, rust_doc=False)}
1313
<%lib:license />

‎src/mako/lib.rs.mako‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
<%
2-
from util import (iter_nested_types, new_context, rust_comment, rust_module_doc_comment, )
2+
from util import (iter_nested_types, new_context, rust_comment, rust_doc_comment,
3+
rust_module_doc_comment, rust_doc_test_norun, canonical_type_name,
4+
rust_test_fn_invisible)
35
nested_schemas = list(iter_nested_types(schemas))
46
5-
c = new_context(resources)
7+
c = new_context(resources)
8+
9+
hub_type = canonical_type_name(canonicalName)
610
%>\
711
<%namespace name="lib" file="lib/lib.mako"/>\
812
<%namespace name="mutil" file="lib/util.mako"/>\
@@ -17,14 +21,54 @@ ${lib.docs(c)}
1721
#![feature(core)]
1822
#![allow(non_snake_case)]
1923

24+
extern crate hyper;
2025
extern crate "rustc-serialize" as rustc_serialize;
2126
extern crate "yup-oauth2" as oauth2;
2227

2328
mod cmn;
2429

2530
use std::collections::HashMap;
31+
use std::marker::PhantomData;
32+
use std::borrow::BorrowMut;
33+
use std::cell::RefCell;
34+
35+
pub use cmn::{Hub, Resource, Part, ResponseResult, RequestResult, NestedType};
36+
37+
// ########
38+
// HUB ###
39+
// ######
40+
41+
/// Central instance to access all ${hub_type} related resource activities
42+
///
43+
/// # Examples
44+
///
45+
/// Instantiate a new hub
46+
///
47+
<%block filter="rust_doc_comment">\
48+
${lib.hub_usage_example()}\
49+
</%block>
50+
pub struct ${hub_type}<C, NC, A> {
51+
client: RefCell<C>,
52+
auth: RefCell<A>,
53+
_m: PhantomData<NC>
54+
}
55+
56+
impl<'a, C, NC, A> Hub for ${hub_type}<C, NC, A> {}
57+
58+
impl<'a, C, NC, A> ${hub_type}<C, NC, A>
59+
where NC: hyper::net::NetworkConnector,
60+
C: BorrowMut<hyper::Client<NC>> + 'a,
61+
A: oauth2::GetToken {
62+
63+
pub fn new(client: C, authenticator: A) -> ${hub_type}<C, NC, A> {
64+
${hub_type} {
65+
client: RefCell::new(client),
66+
auth: RefCell::new(authenticator),
67+
_m: PhantomData,
68+
}
69+
}
70+
}
2671

27-
pub use cmn::{Resource, Part, ResponseResult, RequestResult, NestedType};
2872

2973
// ############
3074
// SCHEMAS ###

‎src/mako/lib/lib.mako‎

Lines changed: 49 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
<%! from util import (activity_split, put_and, md_italic, split_camelcase_s) %>\
1+
<%! from util import (activity_split, put_and, md_italic, split_camelcase_s, canonical_type_name,
2+
rust_test_fn_invisible, rust_doc_test_norun, rust_doc_comment, markdown_rust_block) %>\
23
<%namespace name="util" file="util.mako"/>\
34
4-
<%def name="docs(c)">\
5+
## If rust-doc is True, examples will be made to work for rust doc tests. Otherwise they are set
6+
## for github markdown.
7+
<%def name="docs(c, rust_doc=True)">\
58
<%
69
# fr == fattest resource, the fatter, the more important, right ?
710
fr = None
@@ -54,23 +57,65 @@ let r = hub.${resource}().${activity}(...).${api.terms.action}()
5457
```
5558

5659
The `resource()` and `activity(...)` calls create [builders][builder-pattern]. The second one dealing with `Activities`
57-
supports various methods to configure the impending operation. It is made such that all required arguments have to be
60+
supports various methods to configure the impending operation (not shown here). It is made such that all required arguments have to be
5861
specified right away (i.e. `(...)`), whereas all optional ones can be [build up][builder-pattern] as desired.
5962
The `${api.terms.action}()` method performs the actual communication with the server and returns the respective result.
6063

6164
# Usage (*TODO*)
6265

6366
${'##'} Instantiating the Hub
6467

68+
${self.hub_usage_example(rust_doc)}\
69+
70+
**TODO** Example calls - there should soon be a generator able to do that with proper inputs
6571
${'##'} About error handling
6672

67-
${'##'} About costumization
73+
${'##'} About Customization/Callbacks
6874

6975
[builder-pattern]: http://en.wikipedia.org/wiki/Builder_pattern
7076
[google-go-api]: https://github.com/google/google-api-go-client
7177

7278
</%def>
7379

80+
## Sets up a hub ready for use. You must wrap it into a test function for it to work
81+
## Needs test_prelude.
82+
<%def name="test_hub(hub_type)">\
83+
use oauth2::{Authenticator, DefaultAuthenticatorDelegate, ApplicationSecret, MemoryStorage};
84+
use std::default::Default;
85+
86+
use ${util.library_name()}::${hub_type};
87+
88+
// Get an ApplicationSecret instance by some means. It contains the `client_id` and `client_secret`,
89+
// among other things.
90+
let secret: ApplicationSecret = Default::default();
91+
// Instantiate the authenticator. It will choose a suitable authentication flow for you,
92+
// unless you replace `None` with the desired Flow
93+
// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about what's going on
94+
// You probably want to bring in your own `TokenStorage` to persist tokens and retrieve them from storage.
95+
let auth = Authenticator::new(&secret, DefaultAuthenticatorDelegate,
96+
hyper::Client::new(),
97+
<MemoryStorage as Default>::default(), None);
98+
let mut hub = ${hub_type}::new(hyper::Client::new(), auth);\
99+
</%def>
100+
101+
## You will still have to set the filter for your comment type - either nothing, or rust_doc_comment !
102+
<%def name="hub_usage_example(rust_doc=True)">\
103+
<%
104+
test_filter = rust_test_fn_invisible
105+
main_filter = rust_doc_test_norun
106+
if not rust_doc:
107+
test_filter = lambda s: s
108+
main_filter = markdown_rust_block
109+
%>\
110+
<%block filter="main_filter">\
111+
${util.test_prelude()}\
112+
113+
<%block filter="test_filter">\
114+
${self.test_hub(canonical_type_name(canonicalName))}\
115+
</%block>
116+
</%block>
117+
</%def>
118+
74119
<%def name="license()">\
75120
# License
76121
The **${util.library_name()}** library was generated by ${put_and(copyright.authors)}, and is placed

‎src/mako/lib/util.mako‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,13 @@ ${cargo.repo_base_url}/${OUTPUT_DIR}\
2121

2222
<%def name="library_name()">\
2323
${util.library_name(name, version)}\
24+
</%def>
25+
26+
## All crates and standard `use` declaration, required for all examples
27+
## Must be outside of a test function
28+
<%def name="test_prelude()">\
29+
extern crate hyper;
30+
extern crate "yup-oauth2" as oauth2;
31+
extern crate "rustc-serialize" as rustc_serialize;
32+
extern crate ${self.library_name()};
2433
</%def>

0 commit comments

Comments
 (0)
⚡