From f1d95822f784bce84927c2a9d4134d5477495217 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Tue, 3 Mar 2015 11:16:16 +0100 Subject: [PATCH] feat(doc): def for DO NOT EDIT comments A note like that is now added to all files we generated, commented out depending on the file type. Quite neat, except that for filtering, I always have to use blocks. --- gen/youtube3/LICENSE.md | 5 +++++ gen/youtube3/README.md | 5 +++++ gen/youtube3/cargo.toml | 2 +- gen/youtube3/src/cmn.rs | 21 +++++++++++++++++++++ gen/youtube3/src/lib.rs | 4 ++++ src/mako/LICENSE.md.mako | 4 ++++ src/mako/README.md.mako | 4 ++++ src/mako/cargo.toml.mako | 6 +++--- src/mako/deps.mako | 6 ++++-- src/mako/lib.rs.mako | 4 ++++ src/mako/lib/util.mako | 7 +++++++ src/mako/lib/util.py | 15 +++++++++++++++ 12 files changed, 77 insertions(+), 6 deletions(-) create mode 100644 gen/youtube3/src/cmn.rs diff --git a/gen/youtube3/LICENSE.md b/gen/youtube3/LICENSE.md index 17daa1e3b3..ae22e6ec52 100644 --- a/gen/youtube3/LICENSE.md +++ b/gen/youtube3/LICENSE.md @@ -1,3 +1,8 @@ + The MIT License (MIT) ===================== diff --git a/gen/youtube3/README.md b/gen/youtube3/README.md index 9a82a80649..a214ff1014 100644 --- a/gen/youtube3/README.md +++ b/gen/youtube3/README.md @@ -1,3 +1,8 @@ + The `youtube3` library allows access to all features of *YouTube*. TODO: Library level fully fledged documentation, incuding **summary** and **usage**. diff --git a/gen/youtube3/cargo.toml b/gen/youtube3/cargo.toml index 5f1b16b488..d2769a03e1 100644 --- a/gen/youtube3/cargo.toml +++ b/gen/youtube3/cargo.toml @@ -1,5 +1,5 @@ # DO NOT EDIT ! -# This file was generated automatically by 'src/mako/cargo.toml.mako' +# This file was generated automatically from 'src/mako/cargo.toml.mako' # DO NOT EDIT ! [package] diff --git a/gen/youtube3/src/cmn.rs b/gen/youtube3/src/cmn.rs new file mode 100644 index 0000000000..ccbad6cc41 --- /dev/null +++ b/gen/youtube3/src/cmn.rs @@ -0,0 +1,21 @@ +// COPY OF 'src/rust/cmn.rs' +// DO NOT EDIT +use std::marker::MarkerTrait; + +/// Identifies types which can be inserted and deleted. +/// Types with this trait are most commonly used by clients of this API. +pub trait Resource: MarkerTrait {} + +/// Identifies types which are used in API responses. +pub trait ResponseResult: MarkerTrait {} + +/// Identifies types which are used in API requests. +pub trait RequestResult: MarkerTrait {} + +/// Identifies types which are only used as part of other types, which +/// usually are carrying the `Resource` trait. +pub trait Part: MarkerTrait {} + +/// Identifies types which are only used by other types internally. +/// They have no special meaning, this trait just marks them for completeness. +pub trait NestedType: MarkerTrait {} diff --git a/gen/youtube3/src/lib.rs b/gen/youtube3/src/lib.rs index 9b19252330..7931074beb 100644 --- a/gen/youtube3/src/lib.rs +++ b/gen/youtube3/src/lib.rs @@ -1,3 +1,7 @@ +// DO NOT EDIT ! +// This file was generated automatically from 'src/mako/lib.rs.mako' +// DO NOT EDIT ! + //! TODO: Library level fully fledged documentation, incuding **summary** and **usage**. //! And another line, for testing //! diff --git a/src/mako/LICENSE.md.mako b/src/mako/LICENSE.md.mako index cd85776bb8..7c51da3999 100644 --- a/src/mako/LICENSE.md.mako +++ b/src/mako/LICENSE.md.mako @@ -1,5 +1,9 @@ ## -*- coding: utf-8 -*- <%! import util %>\ +<%namespace name="mutil" file="lib/util.mako"/>\ +<%block filter="util.markdown_comment">\ +<%mutil:gen_info source="${self.uri}" />\ + The MIT License (MIT) ===================== diff --git a/src/mako/README.md.mako b/src/mako/README.md.mako index 13a0251d47..32e1452d65 100644 --- a/src/mako/README.md.mako +++ b/src/mako/README.md.mako @@ -1,5 +1,9 @@ +<%! import util as pyutil %>\ <%namespace name="lib" file="lib/lib.mako"/>\ <%namespace name="util" file="lib/util.mako"/>\ +<%block filter="pyutil.markdown_comment">\ +<%util:gen_info source="${self.uri}" />\ + The `${util.library_name()}` library allows access to all features of *${canonicalName}*. <%lib:docs /> diff --git a/src/mako/cargo.toml.mako b/src/mako/cargo.toml.mako index 0b81485440..32c4113e6f 100644 --- a/src/mako/cargo.toml.mako +++ b/src/mako/cargo.toml.mako @@ -1,8 +1,8 @@ <%! import util %>\ <%namespace name="mutil" file="lib/util.mako"/>\ -# DO NOT EDIT ! -# This file was generated automatically by '${self.uri}' -# DO NOT EDIT ! +<%block filter="util.hash_comment">\ +<%mutil:gen_info source="${self.uri}" />\ + [package] name = "${mutil.library_name()}" diff --git a/src/mako/deps.mako b/src/mako/deps.mako index 90b1ca7c40..12a895d8ed 100644 --- a/src/mako/deps.mako +++ b/src/mako/deps.mako @@ -18,8 +18,10 @@ api_json_inputs = api_json + " $(API_SHARED_INFO)" api_info.append((api_name, api_clean, gen_root)) %>\ -${api_common}: $(RUST_SRC)/cmn.rs - @cp $< $@ +${api_common}: $(RUST_SRC)/cmn.rs $(lastword $(MAKEFILE_LIST)) + @ echo "// COPY OF '$<'" > $@ + @ echo "// DO NOT EDIT" >> $@ + @cat $< >> $@ ${gen_root_stamp}: ${' '.join(i[0] for i in sds)} ${api_json_inputs} $(MAKO_LIB_FILES) $(MAKO_RENDER) PYTHONPATH=$(MAKO_LIB_DIR) $(TPL) --template-dir '.' --var OUTPUT_DIR=$@ -io ${' '.join("%s=%s" % (s, d) for s, d in sds)} --data-files ${api_json_inputs} diff --git a/src/mako/lib.rs.mako b/src/mako/lib.rs.mako index 35ec3ab8e2..2df1388273 100644 --- a/src/mako/lib.rs.mako +++ b/src/mako/lib.rs.mako @@ -8,6 +8,10 @@ <%namespace name="lib" file="lib/lib.mako"/>\ <%namespace name="mutil" file="lib/util.mako"/>\ <%namespace name="schema" file="lib/schema.mako"/>\ +<%block filter="util.rust_comment">\ +<%mutil:gen_info source="${self.uri}" />\ + + <%block filter="util.rust_module_doc_comment">\ <%lib:docs />\ diff --git a/src/mako/lib/util.mako b/src/mako/lib/util.mako index 49cce71ddf..8101652bdf 100644 --- a/src/mako/lib/util.mako +++ b/src/mako/lib/util.mako @@ -1,5 +1,12 @@ <%! import util %>\ +## source should be ${self.uri} +## you need to escape the output, using a filter for example +<%def name="gen_info(source)">\ +DO NOT EDIT ! +This file was generated automatically from '${source}' +DO NOT EDIT !\ + ## This will only work within a substitution, not within python code <%def name="to_api_version(v)">\ diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index cd59936f10..c1454dc27f 100644 --- a/src/mako/lib/util.py +++ b/src/mako/lib/util.py @@ -35,6 +35,21 @@ def rust_module_doc_comment(s): def rust_doc_comment(s): return re_linestart.sub('/// ', s) +# rust comment filter +def rust_comment(s): + return re_linestart.sub('// ', s) + +# hash-based comment filter +def hash_comment(s): + return re_linestart.sub('# ', s) + +# markdown comments +def markdown_comment(s): + nl = '' + if not s.endswith('\n'): + nl = '\n' + return "" % (s, nl) + # escape each string in l with "s" and return the new list def estr(l): return ['"%s"' % i for i in l]