Tutorial for writing a service with an asynchronous client node

[santiago-tapia]

This PR is connected to another PR at example repository: Async Service Example.

This PR includes an intermediate tutorial to write an asynchronous client that sends a request inside a callback. The key feature about the example is that the node execution is not waiting in any where. It is just executing callbacks or spinning, all time.

Besides, it includes some experiments on executing the client in combination with a delayed server, those experiments are designed to help in the understanding of the concept of asynchronism.

[kscottz]

Suggested change

	**All** service **clients** in ROS2 are **asynchronous**. In this tutorial, an example
	**All** service **clients** in ROS 2 are **asynchronous**.
	In this tutorial, an example

[kscottz]

@santiago-tapia we usually do one sentence per line and ROS 2 is always stylized ROS 2.

[kscottz]

I wouldn't assume all readers fully understand what is meant by "asynchronous." We get a lot of undergraduate students reading the docs who may not have reached that point in their education. It would help readability to quickly define your terms and then move on to discussing everything else.

[kscottz]

Suggested change

	In contrast, the following diagram illustrates an asynchronous ROS2 client:
	In contrast, the following diagram illustrates an asynchronous ROS 2 client:

[kscottz]

Suggested change

	the response, meaning its thread is not running but blocked until the
	the response, meaning its thread is blocked (i.e. not running) until the

[kscottz]

Suggested change

	Of course, it could be stopped by invoking a waiting function or another
	blocking function, but this diagram shows a ROS2 client, and in ROS2, to receive
	Of course, it could be stopped by invoking a waiting function or another
	blocking function, but this diagram shows a ROS 2 client, and in ROS 2, to receive

ll 50-53 is a bit of a run-on sentence. I suggest breaking this up into two sentences.

[kscottz]

Suggested change

	Since any service client in ROS2 needs to be spinning to receive the server's
	Since a service client in ROS 2 needs to be spinning to receive the server's

[kscottz]

Suggested change

	response, all clients in ROS2 are asynchronous by design (they cannot simply
	response, all clients in ROS 2 are asynchronous by design (they cannot simply

[kscottz]

Suggested change

	The source code in this tutorial is at `rclcpp examples <https://github.com/ros2/examples/tree/{REPOS_FILE_BRANCH}/rclcpp/services>`,
	The source code for this tutorial is located at `rclcpp examples <https://github.com/ros2/examples/tree/{REPOS_FILE_BRANCH}/rclcpp/services>`.

[kscottz]

Suggested change

you might get the code there directly.

[kscottz]

I think you could simplify this quite a bit. Just say that you've created a server with an arbitrary and artificial delay..

[kscottz]

There's a saying in technical writing that you should, "tell people what you are going to do, tell them what to do, and then tell them what they did."

It may help readability if you preface this tutorial with that you are going to do. Perhaps something like, "In this tutorials we are going to create A and B, and use it evaluate the impact of C on D."

[kscottz]

"at the spinning thread"

This phrasing is a bit unclear to me. Perhaps something like, "Note that since this function uses a callback, it will be executed promptly by the node's main thread while still allowing the node to accomplish other tasks."

[kscottz]

This block, 412-416 could use a bit of revision. It might help to state plainly what the code does, and then contrast with the alternative version.

[kscottz]

Suggested change

	To see what packages that contains *examples_* are registered and available
	To see what packages contain the term *examples_* are available

[kscottz]

This could be shortened. Try to keep it simple for the new users. 😉

[kscottz]

@santiago-tapia thanks for sending us this pull request! I think this contribution could be very helpful for new ROS users learning how to build their first asynchronous client / server pair.

I am going to need you to do a few things so we can help you get this approved.

First, by convention, we request that each sentence gets it own line in your pull request. The reason we request this is that it makes it much easier for us to suggest changes in the file. There were a few places I wanted to make a suggestion but it was difficult to do because of the line breaks. Also, by convention, we stylize it "ROS 2" when written in the docs.

In terms of code I didn't see anything wrong with the pull request. However, the tutorial starts out a little weak, but finishes strong (see my notes at the start of the file). Please keep in mind the audience for the ROS docs are students and developers across the globe, so the shorter and simpler you can make your sentences the better.

If you could address the line break issue in the PR I can make another pass. Once you address those suggestions and we get a second review we can you merged into the docs. Thanks!

[santiago-tapia]

@kscottz, Thank very much for your comments.

I am going to try to solve the issues you mentioned. Just to confirm:

• One sentence per line (without limit to line length?)
• Replace ROS2 with ROS 2
• Make an introduction on Asynchronism at the beginning of the tutorial.
• Other fixes in concrete sentences in the comments above.
• Improve sentences to make them shorter and more concise.

I was wondering if it could be interesting to make a "Concept" article about *asynchronism" and other related concepts. This way the explanations here could be shorter since the reader could find more details somewhere else.

It will take me a while because I have other urgent matters, but I am going to do it as soon as possible.

[kscottz]

One sentence per line (without limit to line length?)

Yep. Generally let your editor deal with line wrapping. Using this approach makes suggestions a whole lot easier on our side.

Replace ROS2 with ROS 2
Make an introduction on Asynchronism at the beginning of the tutorial.
Other fixes in concrete sentences in the comments above.
Improve sentences to make them shorter and more concise.

That sounds about right. Don't work too hard on shortening sentences, I can lend a hand with editing once we have the one sentence per line fixed. One other thing to keep in mind is that our linter is really picky. It tends to complain about trailing whitespace at the end of a line, so I would recommend making whitespace visible in your editor if you can. I can spot fix a few things but it really sucks if every line has an extra space or two at the end.

It will take me a while because I have other urgent matters, but I am going to do it as soon as possible.

No worries! It is the holidays. We really appreciate your contribution to the documentation!

I was wondering if it could be interesting to make a "Concept" article about *asynchronism" and other related concepts. This way the explanations here could be shorter since the reader could find more details somewhere else.

I would be open to it but I think it would help if we were all on the same page before you put a lot of effort into it. What I would recommend is that you file an issue and describe what you want to do with a detailed outline. We can discuss the outline before you sink a lot of effort into writing.

Thanks for being flexible about the idiosyncrasies in our docs contribution process.

[fujitatomoya]

this is whole new section, why we need this redirection?

it specifies one or more alternate URLs from which the page can be redirected. It's useful for maintaining backward compatibility when documentation pages are reorganized or renamed.

[fujitatomoya]

Suggested change

	For information on how to write a basic client/server service see
	:doc:`checkout this tutorial <../../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Service-And-Client>`.
	For information on how to write a basic client/server service see :doc:`Writing a Simple Service and Client <../../Beginner-Client-Libraries/Writing-A-Simple-Cpp-Service-And-Client>`.

[fujitatomoya]

line feed is required in the last?

Suggested change

	@enduml
	@enduml

[santiago-tapia]

Hi again,

I have reviewed the whole tutorial according to the comments from @kscottz and @fujitatomoya.

I am afraid it must be very difficult to track the changes between my previous commit and this last commit because there are lots of changes. That is because I have written every sentence in a line, and, besides, I have reviewed almost every sentence to try to simplify the statements (just, please, remember that English is not my native language and that is not my fault...).

I have also reworked the introduction to say what the reader is going to do and to make a short explanation about asynchronism. That means I have moved some paragraphs and rewritten some others. I have also corrected some other minor details like code indentation. Of course I have replaced ROS2 with ROS 2.

This is my last commit, there is another commit but it is just a merge commit due to a fork synchronization, since this tutorial is completely new, it is not relevant.

Regards,

Santiago