Update README

Gnimuc · Feb 27, 2019 · f03c9eb · f03c9eb
1 parent 3f85189
commit f03c9eb
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://Gnimuc.github.io/CImGui.jl/stable)
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://Gnimuc.github.io/CImGui.jl/dev)
 
-This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization or debug tools.  Browse [Gallery](https://github.com/ocornut/imgui/issues/2265)
+This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization / debug tools. You could browse [Gallery](https://github.com/ocornut/imgui/issues/2265)
 to get an idea of its use cases.
 
 ![demo](demo/demo.png)
@@ -24,7 +24,7 @@ pkg> dev https://github.com/Gnimuc/CImGui.jl.git
 ## Quick Start
 1. Run `demo/demo.jl` to test whether the default backend works on your machine.
 2. Run `examples/demo.jl` and browse demos in the `examples` folder to learn how to use the API.
-3. Press `? CImGui.xxx` to retrieve docs.
+3. Read documentation or run `? CImGui.xxx` to retrieve docs:
 ```
 help?> CImGui.Begin
   Begin(name, p_open=C_NULL, flags=0) -> Bool
@@ -48,17 +48,24 @@ help?> CImGui.Begin
   │  is due to legacy reason and is inconsistent with most other functions (such as
   │  BeginMenu/EndMenu, BeginPopup/EndPopup, etc.) where the EndXXX call should only be
   │  called if the corresponding BeginXXX function returned true.
+```
 
-  ────────────────────────────────────────────────────────────────────────────────────────────────
-
-  Begin(handle::Ptr{ImGuiTextBuffer}) -> Cstring
+## Usage
+The API provided in this package is as close as possible to the original C++ API. When translating C++ code to Julia, please follow the tips below:
+- Replace `ImGui::` to `CImGui.`;
+- `using LibCImGui` to import all of the `ImGuiXXX` types into the current namespace;
+- Member function calling should be translated in Julia style: `fonts.AddFont(cfg)` => `CImGui.Add(fonts, cfg)`;
+- Prefer to define colors as `Vector{Cfloat}` instead of `CImGui.ImVec4`;
+- [CSyntax.jl](https://github.com/Gnimuc/CSyntax.jl) provides two useful macros: `@c` for translating C's `&` operator on immutables and `@cstatic`-block for emulating C's `static` keyword;
+- pointer arithmetic: `&A[n]` should be translated to `pointer(A) + n * sizeof(T)`
 
-  ────────────────────────────────────────────────────────────────────────────────────────────────
+As mentioned before, this package aims to provide the same user experience as the original C++ API, so any high-level abstraction should go into a more high-level package.
 
-  Begin(handle::Ptr{ImGuiListClipper}, items_count, items_height=-1.0)
+### LibCImGui
+LibCImGui is a thin wrapper over cimgui. It's one-to-one mapped to the original cimgui APIs. By using CImGui.LibCImGui, all of the ImGui-prefixed types, enums and ig-prefixed functions are imported into the current namespace.
 
-  Automatically called by constructor if you passed items_count or by Step in Step 1.
-```
+### Backend
+The default backend is based on [ModernGL](https://github.com/JuliaGL/ModernGL.jl) and [GLFW](https://github.com/JuliaGL/GLFW.jl) which are stable and under actively maintained. Other popular backends like [SFML](https://github.com/zyedidia/SFML.jl) and [SDL](https://github.com/ariejdl/SDL.jl) could be added in the future if someone would invest time to make these packages work in post Julia 1.0 era.
 
 ## License
 Only the Julia code in this repo is released under MIT license. Other assets such as those fonts in the `fonts` folder are released under their own license.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,5 +1,5 @@
 # CImGui
-This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization or debug tools.  Browse [Gallery](https://github.com/ocornut/imgui/issues/2265)
+This package provides a Julia language wrapper for [cimgui](https://github.com/cimgui/cimgui): a thin c-api wrapper programmatically generated for the excellent C++ immediate mode gui [Dear ImGui](https://github.com/ocornut/imgui). Dear ImGui is mainly for creating content creation tools and visualization / debug tools. You could browse [Gallery](https://github.com/ocornut/imgui/issues/2265)
 to get an idea of its use cases.
 
 ![demo](demo/demo.png)
@@ -10,4 +10,21 @@ pkg> add CImGui
 ```
 
 ## Usage
-TODO...
+The API provided in this package is as close as possible to the original C++ API. When translating C++ code to Julia, please follow the tips below:
+- Replace `ImGui::` to `CImGui.`;
+- `using LibCImGui` to import all of the `ImGuiXXX` types into the current namespace;
+- Member function calling should be translated in Julia style: `fonts.AddFont(cfg)` => `CImGui.Add(fonts, cfg)`;
+- Prefer to define colors as `Vector{Cfloat}` instead of `CImGui.ImVec4`;
+- [CSyntax.jl](https://github.com/Gnimuc/CSyntax.jl) provides two useful macros: `@c` for translating C's `&` operator on immutables and `@cstatic`-block for emulating C's `static` keyword;
+- pointer arithmetic: `&A[n]` should be translated to `pointer(A) + n * sizeof(T)`
+
+As mentioned before, this package aims to provide the same user experience as the original C++ API, so any high-level abstraction should go into a more high-level package.
+
+### LibCImGui
+LibCImGui is a thin wrapper over cimgui. It's one-to-one mapped to the original cimgui APIs. By using CImGui.LibCImGui, all of the ImGui-prefixed types, enums and ig-prefixed functions are imported into the current namespace.
+
+### Backend
+The default backend is based on [ModernGL](https://github.com/JuliaGL/ModernGL.jl) and [GLFW](https://github.com/JuliaGL/GLFW.jl) which are stable and under actively maintained. Other popular backends like [SFML](https://github.com/zyedidia/SFML.jl) and [SDL](https://github.com/ariejdl/SDL.jl) could be added in the future if someone would invest time to make these packages work in post Julia 1.0 era.
+
+## License
+Only the Julia code in this repo is released under MIT license. Other assets such as those fonts in the `fonts` folder are released under their own license.