[Phoenix] Review: Documentation
Hi, regarding the Phoenix documentation: I'm afraid you lost me not too far from the beginning, and I would like to remark a few things: Details: ======== I am missing details and/or background, maybe even just a sentence or two more, here and there. I assume that for library designers and FP experts most of the things are crystal clear anyways. But for laymen like me, some things are pretty obscure. For example, the actor's page. It says that it is the main concept and it shows a template and with one parameter, which does not appear anywhere near the template's body. And that's pretty much it. It does not say anything about when it is used, by whom, or what the necessary characteristics of the template argument "Eval" are. Nothing. Except: "Don't worry about the details, for now." Sorry, but you lost me there. I do not have the lightest idea of what an actor is all about after reading this page. This certainly leaves a bad feeling, because the one clear statement on the page is "The Actor is the main concept behind the library." Not to worry about details would normally help to focus on the important stuff, the central concept, the main thought. But in this case? I am just being told that the actor is in fact the main concept. I don't know if all the gory details are required on that page, maybe there are too many details already (the template's code). I cannot tell. But I know that the concepts/ideas for this thing need to be explained before going on. In contrast to a crime story, I would prefer to know the plot before going on. When meeting one of the main characters, I do not want to get to know him along with the story. No, I would learn about the characteristics right away and decide whether I want to spend more time reading about him (or using him in one of my projects). I cannot really tell if the following things are documented in enough detail, since I guess I need to understand the concept of the actor. I am afraid, though, that I would require a few more sentences, here and there, or maybe just a few more examples. Examples: ========= IMHO, most examples are either too simple or too abstract. For example: The "real world example" from the starter kit is not really a real world example, it is too simple. So don't throw it away, but add something a little bit more complex. For instance, you could combine it with one from the composite page (which is pretty abstract in my eyes and does not tell me anything): /////////////// struct A { int member; }; A* a = new A; ... (arg1->*&A::member)(a); // returns member a->member /////////////// You could use this in the "real world example". Replace vector<int> by vector<A> and then find objects with object.member%2==1. I assume that would help me. Regards, Roland
On Mon, Sep 29, 2008 at 10:20:25PM +0200, Roland Bock wrote:
For example, the actor's page. It says that it is the main concept and it shows a template and with one parameter, which does not appear anywhere near the template's body. And that's pretty much it. It does not say anything about when it is used, by whom, or what the necessary characteristics of the template argument "Eval" are. Nothing. Except: "Don't worry about the details, for now."
Phoenix manual is meant to be read and understood sequentially. The Actors chapter is roughly at 1/3 of the manual. Actor is a main concept in that it is in the lowest layer of the library (see the Organization chapter), and you need to understand it if you're going to extend Phoenix. You really don't need to bother with details to use ready-made components (while_, operators, bind, etc.). See "Inside Phoenix" chapter for an in-depth explanation of how actors work..
But I know that the concepts/ideas for this thing need to be explained before going on.
I do not think that Phoenix manual is the right place to explain FP concepts. Trying to do so would only get the job half-done, and in this case it might be worse than nothing at all. Though, the introduction _could_ link the concepts ("lambda", "currying", etc.) to some online reference.
You could use this in the "real world example". Replace vector<int> by vector<A> and then find objects with object.member%2==1. I assume that would help me.
You would use bind there. The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML. I'm not sure that any amount of writing can replace direct experience. (And I'm not sure either that one should try to learn FP concepts with a hybrid solution that C++ and Phoenix is.)
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Monday 29 September 2008 16:56 pm, Zeljko Vrba wrote:
The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML. I'm not sure that any amount of writing can replace direct experience. (And I'm not sure either that one should try to learn FP concepts with a hybrid solution that C++ and Phoenix is.)
Are functional programmers who are forced to use C++ (for whatever reason) really the primary audience for Phoenix? And trying to provide a new tool to "normal" C++ programmers is not worth the trouble? It seems like that would give Phoenix a pretty limited audience. I certainly wouldn't bother learning a FP language just so I could come back and understand Phoenix. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQFI4UOh5vihyNWuA4URAhANAKDEdlOaYmnaqn++Va95L9qrGuAHWQCgh5xw PYmk9W/ET9cruvGOYJ9n4XY= =0HH6 -----END PGP SIGNATURE-----
Frank Mori Hess wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On Monday 29 September 2008 16:56 pm, Zeljko Vrba wrote:
The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML. I'm not sure that any amount of writing can replace direct experience. (And I'm not sure either that one should try to learn FP concepts with a hybrid solution that C++ and Phoenix is.)
Are functional programmers who are forced to use C++ (for whatever reason) really the primary audience for Phoenix? And trying to provide a new tool to "normal" C++ programmers is not worth the trouble? It seems like that would give Phoenix a pretty limited audience. I certainly wouldn't bother learning a FP language just so I could come back and understand Phoenix.
IMO, knowledge of FP is not a prerequisite to understanding Phoenix (or lambda or bind for that matter). It would be an advantage though. Regards, -- Joel de Guzman http://www.boostpro.com http://spirit.sf.net
Zeljko Vrba:
The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML.
I'm not sure. The purpose of Phoenix (and Lambda, and boost::bind) is simple: to provide a concise way to create function objects. Most C++ programmers are familiar with the need to write function objects and there is no need to learn SML to take advantage of the basics. Many people start with just needing *_1 < *_2 or bind(&X::name, _1) < bind(&X::name, _2). Some of them simply do not need to go further (or aren't allowed to, by a coding standard).
On Tue, Sep 30, 2008 at 12:30:47AM +0300, Peter Dimov wrote:
Zeljko Vrba:
The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML.
I'm not sure.
The purpose of Phoenix (and Lambda, and boost::bind) is simple: to provide a concise way to create function objects. Most C++ programmers are familiar with the need to write function objects and there is no need to learn SML to take advantage of the basics. Many people start with just needing *_1 < *_2 or bind(&X::name, _1) < bind(&X::name, _2). Some of them simply do not need to go further (or aren't allowed to, by a coding standard).
Good point. But for such simple needs, the manual is then too abstract (there I agree with Roland). And if all you need / are allowed to use is "simple", another thought immediately arises: "this is the same as BLL, just with slightly different syntax". BLL is "a concise way to create function objects", Phoenix is that and a lot more. To understand the "more" part, it helps, IMHO, to know some true FP language.
Zeljko Vrba wrote:
On Tue, Sep 30, 2008 at 12:30:47AM +0300, Peter Dimov wrote:
Zeljko Vrba:
The best way to understand the purpose of Phoenix is, IMHO, to have some first-hand experience with a true functional programming language with type-inference and first-order functions, such as SML. I'm not sure.
The purpose of Phoenix (and Lambda, and boost::bind) is simple: to provide a concise way to create function objects. Most C++ programmers are familiar with the need to write function objects and there is no need to learn SML to take advantage of the basics. Many people start with just needing *_1 < *_2 or bind(&X::name, _1) < bind(&X::name, _2). Some of them simply do not need to go further (or aren't allowed to, by a coding standard).
Good point. But for such simple needs, the manual is then too abstract (there I agree with Roland). And if all you need / are allowed to use is "simple", another thought immediately arises: "this is the same as BLL, just with slightly different syntax". BLL is "a concise way to create function objects", Phoenix is that and a lot more. To understand the "more" part, it helps, IMHO, to know some true FP language.
Agreed. I'll try to cater to the "more" part. Regards, -- Joel de Guzman http://www.boostpro.com http://spirit.sf.net
Roland Bock wrote:
Hi,
regarding the Phoenix documentation: I'm afraid you lost me not too far from the beginning, and I would like to remark a few things:
Details: ======== I am missing details and/or background, maybe even just a sentence or two more, here and there. I assume that for library designers and FP experts most of the things are crystal clear anyways. But for laymen like me, some things are pretty obscure.
Ok, I'll try to provide more background.
For example, the actor's page. It says that it is the main concept and it shows a template and with one parameter, which does not appear anywhere near the template's body. And that's pretty much it. It does not say anything about when it is used, by whom, or what the necessary characteristics of the template argument "Eval" are. Nothing. Except: "Don't worry about the details, for now."
And at that point, it's certainly the case. It's just short of saying that, hey, you need to know about this class, but not in detail. The details will be discussed later.
Sorry, but you lost me there. I do not have the lightest idea of what an actor is all about after reading this page. This certainly leaves a bad feeling, because the one clear statement on the page is "The Actor is the main concept behind the library."
Not to worry about details would normally help to focus on the important stuff, the central concept, the main thought. But in this case? I am just being told that the actor is in fact the main concept.
Yes, and that's all you need to know at that point. More detail will be provided in subsequent sections. Providing the details at this point, IMO, would distract from the main subject matter.
I don't know if all the gory details are required on that page, maybe there are too many details already (the template's code). I cannot tell. But I know that the concepts/ideas for this thing need to be explained before going on.
In contrast to a crime story, I would prefer to know the plot before going on. When meeting one of the main characters, I do not want to get to know him along with the story. No, I would learn about the characteristics right away and decide whether I want to spend more time reading about him (or using him in one of my projects).
I cannot really tell if the following things are documented in enough detail, since I guess I need to understand the concept of the actor. I am afraid, though, that I would require a few more sentences, here and there, or maybe just a few more examples.
The least I could do, perhaps, is to provide links to other parts in the doc where these are explained in detail, for those who are itching to know more. Is that an acceptable solution?
Examples: ========= IMHO, most examples are either too simple or too abstract.
For example: The "real world example" from the starter kit is not really a real world example, it is too simple. So don't throw it away, but add something a little bit more complex. For instance, you could combine it with one from the composite page (which is pretty abstract in my eyes and does not tell me anything):
/////////////// struct A { int member; };
A* a = new A; ...
(arg1->*&A::member)(a); // returns member a->member ///////////////
You could use this in the "real world example". Replace vector<int> by vector<A> and then find objects with object.member%2==1. I assume that would help me.
To be honest, it will be hard to find examples that would please everyone, but you have a good point and I'll try to find a sweet set of examples beyond the "First Practical Example". Regards, -- Joel de Guzman http://www.boostpro.com http://spirit.sf.net
Hi Joel, Joel de Guzman wrote:
For example, the actor's page. It says that it is the main concept and it shows a template and with one parameter, which does not appear anywhere near the template's body. And that's pretty much it. It does not say anything about when it is used, by whom, or what the necessary characteristics of the template argument "Eval" are. Nothing. Except: "Don't worry about the details, for now."
And at that point, it's certainly the case. It's just short of saying that, hey, you need to know about this class, but not in detail. The details will be discussed later.
Well, maybe then it is even too much to show the template code? I admit, I was staring at it, wondering what it might tell me.
Yes, and that's all you need to know at that point. More detail will be provided in subsequent sections. Providing the details at this point, IMO, would distract from the main subject matter.
OK, my point is that I fail to see what the main subject matter is on that page. I promise to learn more about FP and instead of saying "This could be better", I will try to come up with contribution to the documentation.
The least I could do, perhaps, is to provide links to other parts in the doc where these are explained in detail, for those who are itching to know more. Is that an acceptable solution?
Sounds good to me :-)
To be honest, it will be hard to find examples that would please everyone, but you have a good point and I'll try to find a sweet set of examples beyond the "First Practical Example".
Great! Maybe I develop useful examples on my own while learning more about FP. If so, I am going to share them, of course. Thanks for your efforts! Regards, Roland
Roland Bock wrote:
Hi Joel,
Joel de Guzman wrote:
For example, the actor's page. It says that it is the main concept and it shows a template and with one parameter, which does not appear anywhere near the template's body. And that's pretty much it. It does not say anything about when it is used, by whom, or what the necessary characteristics of the template argument "Eval" are. Nothing. Except: "Don't worry about the details, for now."
And at that point, it's certainly the case. It's just short of saying that, hey, you need to know about this class, but not in detail. The details will be discussed later.
Well, maybe then it is even too much to show the template code? I admit, I was staring at it, wondering what it might tell me.
Ehm, no, I don't think so ;) But thinking about it some more, perhaps I can show the real C++ concept, because that's what it really is. Ok, I'll formalize that into a C++ concept form.
Yes, and that's all you need to know at that point. More detail will be provided in subsequent sections. Providing the details at this point, IMO, would distract from the main subject matter.
OK, my point is that I fail to see what the main subject matter is on that page. I promise to learn more about FP and instead of saying "This could be better", I will try to come up with contribution to the documentation.
Great!
The least I could do, perhaps, is to provide links to other parts in the doc where these are explained in detail, for those who are itching to know more. Is that an acceptable solution?
Sounds good to me :-)
To be honest, it will be hard to find examples that would please everyone, but you have a good point and I'll try to find a sweet set of examples beyond the "First Practical Example".
Great! Maybe I develop useful examples on my own while learning more about FP. If so, I am going to share them, of course.
Even greater!
Thanks for your efforts!
Most welcome, Roland. Regards, -- Joel de Guzman http://www.boostpro.com http://spirit.sf.net
participants (5)
-
Frank Mori Hess -
Joel de Guzman -
Peter Dimov -
Roland Bock -
Zeljko Vrba