Various improvements to howto.md #180

jonesmz · 2019-10-09T18:40:45Z

Like last time, I made the following changes

Improvements to English grammar. I am a native English speaker, and have tried to use common phrasing idioms that are clear and concise.
Replaced example of ozo::make_connection with conn_info[io], since ozo::make_connection is deprecated.
Added more explanations of how and why ozo does things the way it does, and tried to fill in details where I struggled initially when researching OZO.

Please feel free to correct any mistakes I have made about the technical implementation details.

Like last time, I made the following changes - Improvements to English grammar. I am a native English speaker, and have tried to use common phrasing idioms that are clear and concise. - Replaced example of `ozo::make_connection` with `conn_info[io]`, since `ozo::make_connection` is deprecated. - Added more explanations of how and why ozo does things the way it does, and tried to fill in details where I struggled initially when researching OZO. Please feel free to correct any mistakes I have made about the technical implementation details.

thed636 · 2019-10-09T18:58:57Z

Michael, thanks a lot!

I've assigned my colleague @koshachy for the review since he doing a rework of How-To document and has a similar PR #171.

bmi-x · 2019-10-11T08:28:46Z

docs/howto.md

@@ -63,12 +69,12 @@ int main() {
        };


If you will make new edits, can you remove unnecessary semicolon? It's confusing.

Did I add that semi-colon...? The diff for the PR doesn't seem to indicate that was changed in this PR.

Of course, not. I think it is an improvement too. And I do not ask you to update your PR only for this change. But if other changes are required, it is good idea (not requirement) to apply this change.

@jonesmz , @bmi-x this PR relates to the part which has significant changes in #171, and it is better to improve the #171 since @koshachy is one who responsible for the future of the documentation.

Hi @jonesmz , thanks for the PR!

There's a lot of changes in my and your PRs and conflicts are inevident. For now, I revise the how-to section at all, so I guess it's better to merge your changes.

I'll review your PR in a few days. And then we can merge it to master.

Sorry for any inconvenience.

@koshachy Ok, sounds good.

koshachy

Thanks for your PR.
I've reviewed the changes and have some questions.

Could you fix them?

Don't hesitate to ask questions if something is unclear or if you want to start a discussion.
You can omit minor issues (tagged Minor).

koshachy · 2019-11-06T13:20:24Z

docs/howto.md

@@ -1,18 +1,18 @@
-# How to


In this case, we'll get the Table of Contents chapter in the left navigation menu.
So I guess it's better to leave the How to name here.

Here is a pic for a better understanding.

koshachy · 2019-11-06T13:20:43Z

docs/howto.md

@@ -39,17 +39,23 @@ int main() {
    ozo::rows_of<std::int64_t, std::optional<std::string>> rows;

    // Connection info with host and port to connect to
-    auto conn_info = ozo::make_connection_info("host=... port=...");
+    // This also supports a PostgreSQL connection URI string
+    ozo::connection_info<> conn_info = ozo::make_connection_info("host=... port=...");


I'm not quite sure about this change.
Could you explain the reason why did you change the auto keyword to the specific type?

koshachy · 2019-11-06T13:21:09Z

docs/howto.md


    // For _SQL literal
    using namespace ozo::literals;
+
+    std::int64_t myParam = ...;


It's better to provide valid code samples.
You can put all the additional information in the comment above the variable definition.

koshachy · 2019-11-06T13:21:42Z

docs/howto.md


-Notice that the second position of the tuple is `std::optional<std::string>`.This is because the `name` field of the table can be _NULL_. Empty optional represents a _NULL_ value (you can learn more about Nullable concept from the documentation). If if a _NULL_ value is retrieved from the database for a type that is not an `std::optional`, then a deserialization error will occur.
+Notice that the second position of the tuple is `std::optional<std::string>`.This is because the `name` field of the table can be _NULL_. An empty optional represents a _NULL_ value (you can learn more about Nullable concept from the  OZO documentation). If if a _NULL_ value is retrieved from the database for a type that is not an `std::optional`, then a deserialization error will occur.


Minor: double space.

koshachy · 2019-11-06T13:22:15Z

docs/howto.md

-Now we need to create a connection information for database to connect to. This is our connection source which can create a connection for us as it will be needed (you can learn more about ConnectionSource and ConnectionProvider concepts from the documentation). It's also acceptable to provide a connection URI string, instead of the comma seperated version.
+Now we need to create a connection information for database to connect to. This is our connection source which can create a connection for us as it will be needed (you can learn more about `ConnectionSource` and `ConnectionProvider` concepts from the documentation). It's also acceptable to provide a connection URI string, instead of the comma seperated version.
+
+Here's how to construct a database query.


I don't think that "construct" is a proper word when we're talking about writing/making queries.

Let's use make or write instead.

koshachy · 2019-11-06T13:23:15Z

docs/howto.md


 ```cpp
-const auto query = "SELECT id, name FROM users_info WHERE amount>="_SQL + std::int64_t(25);
+std::int64_t myParam = ...;


Valid code samples.
See above.

koshachy · 2019-11-06T13:23:21Z

docs/howto.md

+You can also use `ozo::make_query()`, if you prefer to use parameterized queries with the `$1` style notation to indicate your query parameters:
+
+```cpp
+std::int64_t myParam = ...;


Valid code samples.
See above.

koshachy · 2019-11-06T13:24:07Z

docs/howto.md

-//...
-
-const auto query = "SELECT id, name FROM users_info WHERE amount>="_SQL + std::int64_t(25);
+std::int64_t myParam = ...;


Valid code samples.
See above.

koshachy · 2019-11-06T13:25:15Z

docs/howto.md


-Since the mapping is many **C++** types to one **PostgreSQL** type, you can always map another C++ type as PostgreSQL type.
+It defines a type mapping from the C++ type to the specified built-in PostgreSQL type. This mapping also adds compatibility for the various array representations supported by OZO. The current array represantations in OZO are std::vector, std::array, std::list, so for a type that you bind to `std::string`, you can use `std::vector<std::string>`, `std::array<std::string, N>`, `std::list<std::string>` in your queries.


The last sentence in this block is overloaded and it's really difficult to read it.
I guess it is enough to leave the second part of it, isn't it?

... by OZO. You can use std::vector<std::string>, std::array<std::string, N>, std::list<std::string> in your queries.

Or:
Since the current array representations in OZO are std::vector, std::array, std::list, you can use them in your queries: std::vector<std::string>, std::array<std::string, N>, std::list<std::string>.

koshachy · 2019-11-06T13:25:34Z

docs/howto.md


-E.g. we have an in-library `text` type definition like:
+This mapping is many-to-one, allowing you to map multiple C++ types to the same PostgreSQL type. For example, OZO has the built-in mapping for the `text` type like such:


Minor: You can omit all 'like such' and 'like so' expressions in this document that located before code blocks.
Use the colon sign instead.

thed636 requested a review from koshachy October 9, 2019 18:53

bmi-x reviewed Oct 11, 2019

View reviewed changes

koshachy added the docs Documentation related changes and issues label Oct 15, 2019

koshachy requested changes Nov 6, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Various improvements to howto.md #180

Various improvements to howto.md #180

jonesmz commented Oct 9, 2019

thed636 commented Oct 9, 2019

bmi-x Oct 11, 2019

jonesmz Oct 11, 2019

bmi-x Oct 11, 2019

thed636 Oct 11, 2019

koshachy Oct 14, 2019

jonesmz Oct 14, 2019

koshachy left a comment

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019

koshachy Nov 6, 2019


		Notice that the second position of the tuple is `std::optional<std::string>`.This is because the `name` field of the table can be _NULL_. Empty optional represents a _NULL_ value (you can learn more about Nullable concept from the documentation). If if a _NULL_ value is retrieved from the database for a type that is not an `std::optional`, then a deserialization error will occur.
		Notice that the second position of the tuple is `std::optional<std::string>`.This is because the `name` field of the table can be _NULL_. An empty optional represents a _NULL_ value (you can learn more about Nullable concept from the OZO documentation). If if a _NULL_ value is retrieved from the database for a type that is not an `std::optional`, then a deserialization error will occur.


		Since the mapping is many C++ types to one PostgreSQL type, you can always map another C++ type as PostgreSQL type.
		It defines a type mapping from the C++ type to the specified built-in PostgreSQL type. This mapping also adds compatibility for the various array representations supported by OZO. The current array represantations in OZO are std::vector, std::array, std::list, so for a type that you bind to `std::string`, you can use `std::vector<std::string>`, `std::array<std::string, N>`, `std::list<std::string>` in your queries.


		E.g. we have an in-library `text` type definition like:
		This mapping is many-to-one, allowing you to map multiple C++ types to the same PostgreSQL type. For example, OZO has the built-in mapping for the `text` type like such:

Various improvements to howto.md #180

Are you sure you want to change the base?

Various improvements to howto.md #180

Conversation

jonesmz commented Oct 9, 2019

thed636 commented Oct 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

koshachy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment