add more docs, fix linker error for rustc 1.18

Riateche · Riateche · commit 28f499051841 · 2017-06-12T21:02:08.000+03:00
diff --git a/README.md b/README.md
@@ -5,15 +5,37 @@
 
 `cpp_to_rust` allows to use C++ libraries from Rust. The main target of this project is Qt.
 
-## Directions
+## Using published Qt crates
 
-*(Coming soon. Latest versions of Qt crates are not published yet.)*
+This project maintains the following Qt crates (more will hopefully be added in the future):
 
-If you just want to use Qt crates, add them as dependencies to your `Cargo.toml` and see the crates' documentation for more information.
+| Crate       | Version |
+| ----------- | ------- |
+| qt_core     | [![](http://meritbadge.herokuapp.com/qt_core)](https://crates.io/crates/qt_core) |
+| qt_gui      | [![](http://meritbadge.herokuapp.com/qt_gui)](https://crates.io/crates/qt_gui) |
+| qt_widgets  | [![](http://meritbadge.herokuapp.com/qt_widgets)](https://crates.io/crates/qt_widgets) |
+| qt_ui_tools | [![](http://meritbadge.herokuapp.com/qt_ui_tools)](https://crates.io/crates/qt_ui_tools) |
 
-[Online documentation](#) of published Qt crates 
+If you just want to use these crates, add them as dependencies to your `Cargo.toml`, for example:
 
-Published crates required a certain Qt version (currently 5.8) and don't export platform-specific API.
+```
+[dependencies]
+qt_widgets = "0.2"
+```
+
+And add corresponding `extern crate` directives to the crate root (`main.rs` or `lib.rs`):
+
+```
+extern crate qt_widgets;
+```
+
+Each crate re-exports its depenencies, so, for example, you can access `qt_core` as `qt_widgets::qt_core` without adding an explicit dependency.
+
+[Online documentation](https://rust-qt.github.io/rustdoc/qt/qt_core) of published Qt crates (you may also run `cargo doc --open` to generate documentation for your crate's dependencies).
+
+Published crates required a certain Qt version (currently 5.8.0) and don't export platform-specific API.
+
+## Using the generator
 
 If you want to use another Qt version, access platform-specific Qt APIs or tweak the generator configuration, refer to README of [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator) for more information.
 
diff --git a/cpp_to_rust/cpp_to_rust_build_tools/Cargo.toml b/cpp_to_rust/cpp_to_rust_build_tools/Cargo.toml
@@ -4,7 +4,7 @@ name = "cpp_to_rust_build_tools"
 # Don't forget to update `cpp_to_rust/cpp_to_rust_generator/src/versions.rs`
 # and dependency version in qt_build_tools
 # when changing this version.
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Pavel Strakhov <ri@idzaaus.org>"]
 
 description = "Build script implementation for C++ library wrappers"
diff --git a/cpp_to_rust/cpp_to_rust_build_tools/src/lib.rs b/cpp_to_rust/cpp_to_rust_build_tools/src/lib.rs
@@ -141,10 +141,6 @@ impl Config {
     {
       log::status("Generating ffi.rs file");
       let mut ffi_file = create_file(out_dir.with_added("ffi.rs"))?;
-      if ::common::target::current_env() != ::common::target::Env::Msvc {
-        // TODO: make it configurable
-        ffi_file.write("#[link(name = \"stdc++\")]\n")?;
-      }
       if cpp_build_config_data.library_type() == Some(CppLibraryType::Shared) {
         ffi_file
           .write(format!("#[link(name = \"{}\")]\n",
@@ -169,6 +165,10 @@ impl Config {
     for name in cpp_build_config_data.linked_libs() {
       println!("cargo:rustc-link-lib={}", name);
     }
+    if ::common::target::current_env() != ::common::target::Env::Msvc {
+      // TODO: make it configurable
+      println!("cargo:rustc-link-lib=stdc++");
+    }
     for name in cpp_build_config_data.linked_frameworks() {
       println!("cargo:rustc-link-lib=framework={}", name);
     }
diff --git a/cpp_to_rust/cpp_to_rust_generator/src/doc_formatter.rs b/cpp_to_rust/cpp_to_rust_generator/src/doc_formatter.rs
@@ -326,6 +326,12 @@ pub fn doc_for_qt_builtin_receiver_method(cpp_type_name: &str,
           cpp_method = receiver.original_method_name)
 }
 
+pub fn doc_for_qt_builtin_receivers_struct(rust_type_name: &str, receiver_type: &str) -> String {
+  format!("Provides access to built-in Qt {} of `{}`.",
+          receiver_type,
+          rust_type_name)
+}
+
 pub fn add_special_type_docs(data: &mut RustTypeDeclaration) -> Result<()> {
   let mut type_doc = None;
   if let RustTypeDeclarationKind::CppTypeWrapper {
diff --git a/cpp_to_rust/cpp_to_rust_generator/src/launcher.rs b/cpp_to_rust/cpp_to_rust_generator/src/launcher.rs
@@ -323,6 +323,7 @@ pub fn run(config: Config) -> Result<()> {
     cpp_ffi_lib_name: cpp_ffi_lib_name.clone(),
     generator_dependencies: &dependencies,
     write_dependencies_local_paths: config.write_dependencies_local_paths(),
+    cpp_lib_version: config.cpp_lib_version().map(|s| s.into()),
   };
   let mut dependency_rust_types = Vec::new();
   for dep in &dependencies {
diff --git a/cpp_to_rust/cpp_to_rust_generator/src/rust_code_generator.rs b/cpp_to_rust/cpp_to_rust_generator/src/rust_code_generator.rs
@@ -33,6 +33,8 @@ pub struct RustCodeGeneratorConfig<'a> {
   pub crate_template_path: Option<PathBuf>,
   /// Name of the C++ wrapper library.
   pub cpp_ffi_lib_name: String,
+  /// Version of the original C++ library.
+  pub cpp_lib_version: Option<String>,
   /// `cpp_to_rust` based dependencies of the generated crate.
   pub generator_dependencies: &'a [DependencyInfo],
   /// As in `Config`.
@@ -996,7 +998,11 @@ impl<'a> RustCodeGenerator<'a> {
                   }
                 };
                 let mut struct_content = Vec::new();
-                content.push(format!("pub struct {}<'a>(&'a {});\n", struct_type, obj_name));
+                content.push(format!("{}pub struct {}<'a>(&'a {});\n",
+                                     format_doc(&doc_formatter::doc_for_qt_builtin_receivers_struct(
+                                       type1.name.last_name()?, struct_method)),
+
+                                                                                                   struct_type, obj_name));
                 for receiver in qt_receivers {
                   if &receiver.receiver_type == receiver_type {
                     let arg_texts: Vec<_> = receiver
@@ -1296,14 +1302,22 @@ impl<'a> {connections_mod}::Receiver for {type_name}<'a> {{
 
   /// Creates new Rust source file or merges it with the existing file.
   fn save_src_file(&self, path: &Path, code: &str) -> Result<()> {
-    const MARKER: &'static str = "include_generated!();";
+    const INCLUDE_GENERATED_MARKER: &'static str = "include_generated!();";
+    const CPP_LIB_VERSION_MARKER: &'static str = "{cpp_to_rust.cpp_lib_version}";
     if path.exists() {
-      let template = file_to_string(path)?;
-      if let Some(index) = template.find(MARKER) {
+      let mut template = file_to_string(path)?;
+      if template.contains(CPP_LIB_VERSION_MARKER) {
+        if let Some(ref cpp_lib_version) = self.config.cpp_lib_version {
+          template = template.replace(CPP_LIB_VERSION_MARKER, cpp_lib_version);
+        } else {
+          return Err("C++ library version was not set in configuration.".into());
+        }
+      }
+      if let Some(index) = template.find(INCLUDE_GENERATED_MARKER) {
         let mut file = create_file(&path)?;
         file.write(&template[0..index])?;
         file.write(code)?;
-        file.write(&template[index + MARKER.len()..])?;
+        file.write(&template[index + INCLUDE_GENERATED_MARKER.len()..])?;
       } else {
         let name = os_str_to_str(path
                                    .file_name()
diff --git a/cpp_to_rust/cpp_to_rust_generator/src/versions.rs b/cpp_to_rust/cpp_to_rust_generator/src/versions.rs
@@ -8,7 +8,7 @@
 
 
 /// Version of `cpp_to_rust_build_tools` crate.
-pub const BUILD_TOOLS_VERSION: &'static str = "0.2.0";
+pub const BUILD_TOOLS_VERSION: &'static str = "0.2.1";
 
 /// Version of `cpp_utils` crate.
 pub const CPP_UTILS_VERSION: &'static str = "0.2.0";
diff --git a/qt_generator/qt_build_tools/Cargo.toml b/qt_generator/qt_build_tools/Cargo.toml
@@ -2,12 +2,12 @@
 name = "qt_build_tools"
 
 # when changing this version, update `qt_generator/qt_generator/src/versions.rs`
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Pavel Strakhov <ri@idzaaus.org>"]
 license = "MIT"
 description = "Build script implementation for Rust Qt crates"
 repository = "https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_build_tools"
 
 [dependencies]
-cpp_to_rust_build_tools = { version = "0.2.0", path = "../../cpp_to_rust/cpp_to_rust_build_tools" }
+cpp_to_rust_build_tools = { version = "0.2.1", path = "../../cpp_to_rust/cpp_to_rust_build_tools" }
 qt_generator_common = { version = "0.2.0", path = "../qt_generator_common" }
diff --git a/qt_generator/qt_generator/crate_templates/core/src/lib.rs b/qt_generator/qt_generator/crate_templates/core/src/lib.rs
@@ -7,9 +7,17 @@
 //! Some methods are unsafe even though they are not marked as unsafe.
 //! Users must carefully track ownership of the objects, as usual Rust guarantees
 //! do not take effect. This will hopefully improve in the future.
-//! Please peport any issues to the
+//! Please report any issues to the
 //! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
 //!
+//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
+//! If Qt compatibility guarantees take effect, it should be compatible
+//! with future minor releases and with past and future patch releases,
+//! but API added in future releases won't be available. The crate is not compatible
+//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
+//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
+//! to generate crates for your Qt version.
+//!
 //! # Starting up
 //!
 //! Qt requires an application object to be constructed at the beginning of the application.
diff --git a/qt_generator/qt_generator/crate_templates/gui/src/lib.rs b/qt_generator/qt_generator/crate_templates/gui/src/lib.rs
@@ -1,5 +1,28 @@
 //! Bindings for [QtGui](http://doc.qt.io/qt-5/qtgui-module.html) library.
 //!
 //! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
+//!
+//! This is work in progress, so the API will significantly change in the future.
+//! Some methods are missing, and some are inconvenient to use.
+//! Some methods are unsafe even though they are not marked as unsafe.
+//! Users must carefully track ownership of the objects, as usual Rust guarantees
+//! do not take effect. This will hopefully improve in the future.
+//! Please report any issues to the
+//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
+//!
+//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
+//! If Qt compatibility guarantees take effect, it should be compatible
+//! with future minor releases and with past and future patch releases,
+//! but API added in future releases won't be available. The crate is not compatible
+//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
+//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
+//! to generate crates for your Qt version.
+//!
+//! Refer to `qt_core` crate documentation for general information about Qt crates.
+//! Note that if you use `qt_widgets`, you should use `qt_widgets::application::Application`
+//! as the application object, and if you use `qt_gui` but not `qt_widgets`, you should use
+//! `qt_gui::gui_application::GuiApplication`.
+
+
 
 include_generated!();
diff --git a/qt_generator/qt_generator/crate_templates/ui_tools/src/lib.rs b/qt_generator/qt_generator/crate_templates/ui_tools/src/lib.rs
@@ -1,5 +1,23 @@
 //! Bindings for [QtUiTools](http://doc.qt.io/qt-5/qtuitools-module.html) library.
 //!
 //! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
+//!
+//! This is work in progress, so the API will significantly change in the future.
+//! Some methods are missing, and some are inconvenient to use.
+//! Some methods are unsafe even though they are not marked as unsafe.
+//! Users must carefully track ownership of the objects, as usual Rust guarantees
+//! do not take effect. This will hopefully improve in the future.
+//! Please report any issues to the
+//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
+//!
+//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
+//! If Qt compatibility guarantees take effect, it should be compatible
+//! with future minor releases and with past and future patch releases,
+//! but API added in future releases won't be available. The crate is not compatible
+//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
+//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
+//! to generate crates for your Qt version.
+//!
+//! Refer to `qt_core` crate documentation for general information about Qt crates.
 
 include_generated!();
diff --git a/qt_generator/qt_generator/crate_templates/widgets/src/lib.rs b/qt_generator/qt_generator/crate_templates/widgets/src/lib.rs
@@ -1,5 +1,25 @@
 //! Bindings for [QtWidgets](http://doc.qt.io/qt-5/qtwidgets-module.html) library.
 //!
 //! This crate was generated using [cpp_to_rust](https://github.com/rust-qt/cpp_to_rust).
+//!
+//! This is work in progress, so the API will significantly change in the future.
+//! Some methods are missing, and some are inconvenient to use.
+//! Some methods are unsafe even though they are not marked as unsafe.
+//! Users must carefully track ownership of the objects, as usual Rust guarantees
+//! do not take effect. This will hopefully improve in the future.
+//! Please report any issues to the
+//! [issue tracker](https://github.com/rust-qt/cpp_to_rust/issues).
+//!
+//! This crate was generated for **Qt {cpp_to_rust.cpp_lib_version}**.
+//! If Qt compatibility guarantees take effect, it should be compatible
+//! with future minor releases and with past and future patch releases,
+//! but API added in future releases won't be available. The crate is not compatible
+//! with past minor Qt releases. If you need to use a Qt version incompatible with this crate,
+//! use [qt_generator](https://github.com/rust-qt/cpp_to_rust/tree/master/qt_generator/qt_generator)
+//! to generate crates for your Qt version.
+//!
+//! Refer to `qt_core` crate documentation for general information about Qt crates.
+//! Note that if you use `qt_widgets`, you should use `qt_widgets::application::Application`
+//! as the application object.
 
 include_generated!();
diff --git a/qt_generator/qt_generator/src/versions.rs b/qt_generator/qt_generator/src/versions.rs
@@ -1,3 +1,5 @@
+/// Actual version of `qt_build_tools` crate used as build dependency
+pub const QT_BUILD_TOOLS_VERSION: &'static str = "0.2.1";
 
-pub const QT_BUILD_TOOLS_VERSION: &'static str = "0.2.0";
-pub const QT_OUTPUT_CRATES_VERSION: &'static str = "0.2.0";
+/// Version of all generated Qt crates
+pub const QT_OUTPUT_CRATES_VERSION: &'static str = "0.2.2";
