Documentation updates, test fixes.

src/context.rs

@@ -1,25 +1,7 @@
-// TODO(4bb4) Do this properly.
-// I already added a simple Context struct that can be created once and used as long as it is not
-// dropped here for initial tests - this is of course neither threadsafe nor otherwise safe to use
-// unless one "does it right", so it's not a real solution.
-//
-// The context should have to be created, and ideally it should be difficult to impossible
-// to do things without having a context. implot-rs makes it so that there is a context and
-// that context has a "frame()" function that returns a Ui, and that Ui is then used to create
-// widgets. Windows are built with a build() function that takes a reference to that Ui as an
-// argument, but also have a begin() function that take a context and put it in their token.
-//
-// I think I'll mirror that here, except that we don't need a frame() function, it's enough
-// to create a context once and then keep passing it around. I'll hence need a mutex and
-// a mechansim similar (or equal) to what imgui-rs does for making sure there can only be
-// a single context. Implementation could go roughly like this:
-//
-// - Add a mutex for modifying context things
-// - Make creation and drop functions use that mutex
-// - Change Plot, PlotLine, PlotScatter, PlotBars, PlotText to all require a context.
-//   I think I'll call this PlotUi to mimmick imgui-rs' Ui.
-// - Think about what this means in terms of the stacks and things like is_plot_hovered() -
-//   they should also only work when there is a context available.
+//! Module for handling the ImPlot context. This is modeled quite directly after how
+//! this is dealt with in imgui-rs, because it follows the same concepts and doing this
+//! also helps readability if one is already familiar with the imgui code.
+
 use parking_lot::ReentrantMutex;
 
 use crate::PlotUi;
@@ -27,7 +9,9 @@ use crate::PlotUi;
 /// An implot context.
 ///
 /// A context is required to do most of the things this library provides. While this was created
-/// implicitly in earlier versions of the library, it is now created explicitly.
+/// implicitly in earlier versions of the library, it is now created explicitly. These contexts
+/// cannot currently be disabled through the high level API. This could be implemented though,
+/// if you need multiple contexts that you can switch around between, file an issue.
 pub struct Context {
     raw: *mut sys::ImPlotContext,
 }
@@ -43,7 +27,8 @@ fn no_current_context() -> bool {
 }
 
 impl Context {
-    /// Create a context.
+    /// Create a context. This will also activate the context in ImPlot, and hence creating
+    /// a second context when one already exists is an error and will panic.
     pub fn create() -> Self {
         let _guard = CTX_MUTEX.lock();
         assert!(
@@ -58,7 +43,8 @@ impl Context {
         Self { raw: ctx }
     }
 
-    /// Get a "plot ui" struct, this will be used to build actual plots.
+    /// Get a "plot ui" struct, this will be used to build actual plots and is quite
+    /// analogous to imgui-rs' "Ui" struct.
     pub fn get_plot_ui(&self) -> PlotUi {
         PlotUi { context: self }
     }

src/lib.rs

@@ -6,8 +6,13 @@
 //! itself (in particular also the demo code [here](https://github.com/epezent/implot/blob/master/implot_demo.cpp))
 //! should help as well.
 //!
+//! For usage examples, see the `implot-examples` crate - it contains standalone runnable examples
+//! that showcase the API and features of this crate. The [Github readme](https://github.com/4bb4/implot-rs)
+//! lists the features that are already implemented as idiomatic bindings. For everything else, if
+//! you'd really like a particular feature, file an issue and it'll be given priority for wrapping,
+//! or directly contribute a PR, or use the low-level bindings directly for the time being.
 //!
-pub extern crate implot_sys as sys;
+extern crate implot_sys as sys;
 
 #[macro_use]
 extern crate lazy_static;

src/plot.rs

@@ -79,9 +79,11 @@ bitflags! {
 /// `Plot` is to be used (within an imgui window) with the following pattern:
 /// ```no_run
 /// # use implot;
+/// let plotting_context = implot::Context::create();
+/// let plot_ui = plotting_context.get_plot_ui();
 /// implot::Plot::new("my title")
 ///     .size(300.0, 200.0) // other things such as .x_label("some_label") can be added too
-///     .build( || {
+///     .build(&plot_ui, || {
 ///         // Do things such as plotting lines
 ///     });
 ///

src/plot_elements.rs

@@ -1,3 +1,8 @@
+//! # Plot elements module
+//!
+//! This module defines the various structs that can be used for drawing different things such
+//! as lines, bars, scatter plots and text in a plot. For the module to create plots themselves,
+//! see `plot`.
 use sys::imgui::im_str;
 
 // --- Actual plotting functionality -------------------------------------------------------------