Re: [Chicken-users] Re: dbus:send bug
Hello, Documentation for eggs is usually manually written. As far as I know, nobody uses automatic extraction of comments from code. Look at the contracts egg. Using it, you will not only get automatic documentation of your modules but also a simple version of Design by Contract invented by Bertrand Meyer for its Eiffel language. Cheers Juergen Dr. Juergen Lorenz Flensburger Str. 12 D 10557 Berlin ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 4:45 PM, Peter Bex peter@xs4all.nl wrote:
On Wed, Mar 16, 2011 at 04:52:45PM -0300, Stephen Eilert wrote:
Almost all the extracted documentation I've seen is of shitty quality;
people tend to use automatic extraction of docs as an excuse not to
write proper documentation.
As opposed to not writing it at all, or having it get out of sync with
the code, as they live in different places.
That's an invalid argument; I've seen countless cases of inline docs
which say one thing while the code *right below it* does something
completely different. When the docs are elsewhere, at least you
won't be tempted to skim the comments and skip the code while reading
the source.
Also, it is trivial to extract documentation for, say, an older egg
version. Which is in sync with the code, by default.
When you have documentation in the code, it goes wherever that code goes.
That much is true.
{snip}
One can make the argument that it would be *easier* to document the
code because you are looking at it, it is sitting right next to the
docs.
You can also make the argument that you're being distracted by the way
the code is laid out. If you are documenting completely separately,
you can think about the flow of text that makes most sense, grouping
procedures that fit together logically. {snip}
A system that I think works pretty well is:
1. separate standalone docs for things like overview, tutorial,
cheatsheet, cookbook
2. API docs in the source code file (easily extracted), though, all
placed together at the end
3. comments for low-level explanations of why something is done a certain way
For example, often in Perl 5:
* (1) are put in separate .pod files,
* (2) are put after a special marker at the end of the source code
(__END__) so the compiler can skip it
* both (1) and (2) are accessed the same way using the `perldoc` command
---John
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Thu, Mar 17, 2011 at 09:17:13AM -0400, John Gabriele wrote:
You can also make the argument that you're being distracted by the way
the code is laid out. If you are documenting completely separately,
you can think about the flow of text that makes most sense, grouping
procedures that fit together logically. {snip}
A system that I think works pretty well is:
1. separate standalone docs for things like overview, tutorial,
cheatsheet, cookbook
2. API docs in the source code file (easily extracted), though, all
placed together at the end
3. comments for low-level explanations of why something is done a certain way
That means three times the amount of work for the programmer. And in
practice, that means 1 and 3 are not going to be done. Like I said,
automatically generated documentation is often used as an excuse by
the lazy not to do proper documentation.
It also means more work and headaches for the maintainers of the Chicken
infrastructure to accomodate for all these new fancy ways of doing
documentation, and more explaining to users why their docs are so
fragmented.
So unless you're willing to draft up a full proposal on how this will
integrate in our infrastructure and write all the required code, I
suggest we stop this pointless discussion. We're already having a
similar, equally pointless, discussion on the other list :(
Cheers,
Peter
--
http://sjamaan.ath.cx
--
The process of preparing programs for a digital computer
is especially attractive, not only because it can be economically
and scientifically rewarding, but also because it can be an aesthetic
experience much like composing poetry or music.
-- Donald Knuth
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
Hi John! This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. First of all, thanks for your detailed report! As you are the first user of this egg after a long time I would suspect some bitrot. Please feel free to change the wiki page as you see fit and maybe send patches for the egg to the author, maybe cc'ed to this list. I hope you are not put off by all the dust that has set on this extension. Let's make it better! Kind regards, Christian ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] Re: dbus:send bug
Christian Kellermann ck...@pestilenz.org writes: Hi John! This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. First of all, thanks for your detailed report! As you are the first user of this egg after a long time I would suspect some bitrot. Please feel free to change the wiki page as you see fit and maybe send patches for the egg to the author, maybe cc'ed to this list. I hope you are not put off by all the dust that has set on this extension. Let's make it better! Kind regards, Christian Okay, great. For some reason I hadn't noticed that I could edit that page. I thought the egg pages were auto-generated from inline comments in the eggs themselves (or something). So I will work on cleaning that up and contact the author about the couple of bugs I've found in the code itself. Many thanks -- John Foerch ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
Hi John, On Wed, 16 Mar 2011 12:55:54 -0400 John J Foerch jjfoe...@earthlink.net wrote: Christian Kellermann ck...@pestilenz.org writes: This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. First of all, thanks for your detailed report! As you are the first user of this egg after a long time I would suspect some bitrot. Please feel free to change the wiki page as you see fit and maybe send patches for the egg to the author, maybe cc'ed to this list. I hope you are not put off by all the dust that has set on this extension. Let's make it better! Okay, great. For some reason I hadn't noticed that I could edit that page. I thought the egg pages were auto-generated from inline comments in the eggs themselves (or something). So I will work on cleaning that up and contact the author about the couple of bugs I've found in the code itself. Excellent. Documentation for eggs is usually manually written. As far as I know, nobody uses automatic extraction of comments from code. Best wishes. Mario -- http://parenteses.org/mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
* John J Foerch jjfoe...@earthlink.net [110316 17:59]: Christian Kellermann ck...@pestilenz.org writes: Hi John! This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. First of all, thanks for your detailed report! As you are the first user of this egg after a long time I would suspect some bitrot. Please feel free to change the wiki page as you see fit and maybe send patches for the egg to the author, maybe cc'ed to this list. I hope you are not put off by all the dust that has set on this extension. Let's make it better! Kind regards, Christian Okay, great. For some reason I hadn't noticed that I could edit that page. I thought the egg pages were auto-generated from inline comments in the eggs themselves (or something). So I will work on cleaning that up and contact the author about the couple of bugs I've found in the code itself. Cool! You are not the first user not noticing that he could edit the page. What can we do to improve the situation there? I am asking because stuff like this gets forgotten quickly by newcomers and then it is all obvious...until the next new person shows up... Kind regards, Christian ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 2:03 PM, Mario Domenech Goulart mario.goul...@gmail.com wrote: Hi John, On Wed, 16 Mar 2011 12:55:54 -0400 John J Foerch jjfoe...@earthlink.net wrote: Christian Kellermann ck...@pestilenz.org writes: This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. First of all, thanks for your detailed report! As you are the first user of this egg after a long time I would suspect some bitrot. Please feel free to change the wiki page as you see fit and maybe send patches for the egg to the author, maybe cc'ed to this list. I hope you are not put off by all the dust that has set on this extension. Let's make it better! Okay, great. For some reason I hadn't noticed that I could edit that page. I thought the egg pages were auto-generated from inline comments in the eggs themselves (or something). So I will work on cleaning that up and contact the author about the couple of bugs I've found in the code itself. Excellent. Documentation for eggs is usually manually written. As far as I know, nobody uses automatic extraction of comments from code. And that's a shame. --Stephen Sent from my Emacs ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 02:58:59PM -0300, Stephen Eilert wrote: Documentation for eggs is usually manually written. As far as I know, nobody uses automatic extraction of comments from code. And that's a shame. Why? Almost all the extracted documentation I've seen is of shitty quality; people tend to use automatic extraction of docs as an excuse not to write proper documentation. Also, writing documentation by hand forces one to think about writing it in a way that it can be read from beginning to end and have it make sense. Having documentation on a wiki means people can add notes about and rewrite sections they found difficult or hard to understand, thereby increasing overall quality. Finally, when the inline documentation *is* done really well, you end up with a lot of documentation getting in the way when you're trying to read the code. Cheers, Peter -- http://sjamaan.ath.cx -- The process of preparing programs for a digital computer is especially attractive, not only because it can be economically and scientifically rewarding, but also because it can be an aesthetic experience much like composing poetry or music. -- Donald Knuth ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 3:34 PM, Peter Bex peter@xs4all.nl wrote: On Wed, Mar 16, 2011 at 02:58:59PM -0300, Stephen Eilert wrote: Documentation for eggs is usually manually written. As far as I know, nobody uses automatic extraction of comments from code. And that's a shame. Why? Almost all the extracted documentation I've seen is of shitty quality; people tend to use automatic extraction of docs as an excuse not to write proper documentation. As opposed to not writing it at all, or having it get out of sync with the code, as they live in different places. Also, it is trivial to extract documentation for, say, an older egg version. Which is in sync with the code, by default. When you have documentation in the code, it goes wherever that code goes. Also, writing documentation by hand forces one to think about writing it in a way that it can be read from beginning to end and have it make sense. But that's usually done after the code has been written, as an afterthought. Having documentation on a wiki means people can add notes about and rewrite sections they found difficult or hard to understand, thereby increasing overall quality. Notes can be added no matter how the documentation is generated. As for rewriting sections, I agree with you - it is easier in a wiki. It would be helpful to know how often that happens in practice, though. One can make the argument that it would be *easier* to document the code because you are looking at it, it is sitting right next to the docs. If you are reading it in the source you can even spot the fact that, say, a function's arguments are documented wrong, because you can see it right there. Finally, when the inline documentation *is* done really well, you end up with a lot of documentation getting in the way when you're trying to read the code. That is also true. See, for instance, ActiveRecord. It has benefits too - you can see the documentation right next to the section you are editing or trying to understand and breaks up code sections visually (when done well). I have stopped complaining about the lack of docstrings when chicken-doc (and chickadee) was created. It is not an ideal solution (from my point of view), but it mostly solves the problem of retrieving the documentation for chicken and eggs in the repository. However, I still think that it could be useful. If not for Core and Eggs, then perhaps for our own Scheme projects. Maybe some hack using Hyde? --Stephen Sent from my Emacs ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] Re: dbus:send bug
Christian Kellermann ck...@pestilenz.org writes: * John J Foerch jjfoe...@earthlink.net [110316 17:59]: Okay, great. For some reason I hadn't noticed that I could edit that page. I thought the egg pages were auto-generated from inline comments in the eggs themselves (or something). So I will work on cleaning that up and contact the author about the couple of bugs I've found in the code itself. Cool! You are not the first user not noticing that he could edit the page. What can we do to improve the situation there? I am asking because stuff like this gets forgotten quickly by newcomers and then it is all obvious...until the next new person shows up... I think that when I didn't see a link to 'log in' or 'create account', I didn't bother investigating further to see if anonymous editing was allowed. Now I have an account in any case, so it's all good. -- John Foerch ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
Stephen Eilert scripsit: One can make the argument that it would be *easier* to document the code because you are looking at it, it is sitting right next to the docs. If you are reading it in the source you can even spot the fact that, say, a function's arguments are documented wrong, because you can see it right there. Egg documentation should not be documentation of the code (implementation) of the egg, but of its interface. -- XQuery Blueberry DOMJohn Cowan Entity parser dot-com co...@ccil.org Abstract schemata http://www.ccil.org/~cowan XPointer errata Infoset Unicode BOM --Richard Tobin ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 04:52:45PM -0300, Stephen Eilert wrote: Almost all the extracted documentation I've seen is of shitty quality; people tend to use automatic extraction of docs as an excuse not to write proper documentation. As opposed to not writing it at all, or having it get out of sync with the code, as they live in different places. That's an invalid argument; I've seen countless cases of inline docs which say one thing while the code *right below it* does something completely different. When the docs are elsewhere, at least you won't be tempted to skim the comments and skip the code while reading the source. Also, it is trivial to extract documentation for, say, an older egg version. Which is in sync with the code, by default. When you have documentation in the code, it goes wherever that code goes. That much is true. Also, writing documentation by hand forces one to think about writing it in a way that it can be read from beginning to end and have it make sense. But that's usually done after the code has been written, as an afterthought. Yeah, just like inline docs. With inline docs it's worse; witness the countless ruby libraries where you think you get docs for a method because it's listed in the index, only to find an empty line staring at you when you click it. Utterly frustrating, that! If it isn't documented and it won't show up in the docs, at least you won't start wondering whether it's intended to be part of the official API or it will be gone in the next version, and if you're even using it as intended. Having documentation on a wiki means people can add notes about and rewrite sections they found difficult or hard to understand, thereby increasing overall quality. Notes can be added no matter how the documentation is generated. As for rewriting sections, I agree with you - it is easier in a wiki. It would be helpful to know how often that happens in practice, though. It does happen. Not super-often though. You can look through the logs if you want concrete numbers. Most are simple fixes of spelling mistakes or markup fixes, to be sure, but you can also be sure those wouldn't be done when it would require making a patch and submitting that to the author! One can make the argument that it would be *easier* to document the code because you are looking at it, it is sitting right next to the docs. You can also make the argument that you're being distracted by the way the code is laid out. If you are documenting completely separately, you can think about the flow of text that makes most sense, grouping procedures that fit together logically. Sometimes code is organised in one way because that's more convenient or logical when defining similar procedures together, but it makes more sense to document them for a newbie. For example, you can have the docs talk about a low-level API and a high-level API, while you group the code together so that low-level procedure A1, A2 and A3 are followed immediately by the high-level procedure A that combines the three in a smart way. If you are reading it in the source you can even spot the fact that, say, a function's arguments are documented wrong, because you can see it right there. Generally when documenting the procedures you're not doing it straight from memory; you have another buffer with the source open which you consult occasionally. Finally, when the inline documentation *is* done really well, you end up with a lot of documentation getting in the way when you're trying to read the code. That is also true. See, for instance, ActiveRecord. Ah, Rails. The perfect example of what I hate about inline docs. Those classes are prefaced with pages upon pages of text, and you can't easily find the code. Also, the code is very hairy and convoluted, but all the text obscures that fact. Besides, the Rails docs are one of the worst ones. All the text is grouped together because that makes most sense in the documentation tool, and then you get lots of scantily-documented methods. When you click in the index on a method to find the docs, you basically get almost nothing. You're expected to know that you can scroll up to find the actual documentation, or - worse - to know the right related class you should click because that's where the real docs are. See for example: http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html A bit of docs for one method, the other ones have _zero_ documentation. For example, what the *hell* does find_or_instantiator_by_attributes(match, attributes, *args) do? Nice that the code is right there, but it's so winding and convoluted I sure can't find out what it does by skimming it. If I'm not supposed to use it as an API end user, what is it doing in the docs? Another glorious example: http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Column/Format.html What's that used for? My guess is it's some internal thing, but who
Re: [Chicken-users] Re: dbus:send bug
On Wed, Mar 16, 2011 at 5:46 PM, Peter Bex peter@xs4all.nl wrote: On Wed, Mar 16, 2011 at 04:39:46PM -0400, John Cowan wrote: Egg documentation should not be documentation of the code (implementation) of the egg, but of its interface. Thank you for that. You made my point more concisely than I could ever hope to. Very well. I'll stop the bikeshedding. For now. Mwahahahah. --Stephen Sent from my Emacs ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] Re: dbus:send bug
John J Foerch jjfoe...@earthlink.net writes: There seems to be an error in dbus:send in the dbus egg. As a test case, the first example given in the dbus egg docs will show the problem: http://wiki.call-cc.org/eggref/4/dbus#examples-you-can-test-with-qt On further research, it seems that the bulk of the problem is that dbus:send is entirely mis-documented. That is, it doesn't do what the documentation and examples say it does, but what it does do is still a necessary and useful feature for the bindings to provide. Here is a fairly thorough list of what is wrong with the documentation, so hopefully we can use this to fix it up: Goals and Status * send signals (messages) This is misleading. Signals are a type of message, but not all messages are signals. DBus in General * signal: ... A reply is not necessarily required. This sentence should be omitted or changed. Signals are one-way, period. Some of those would seem to be optional, because the total namespace ends up much deeper than e.g. a URL. However not enough testing has been done to confirm that if you leave out the service and the interface, for example, you won't miss them. Interfaces are optional for both methods and signals. Services are required for methods, but not used at all for signals. Exported functions * dbus:send : send a message, and don't bother waiting for the response. This is misleading. It should say send a signal instead of message. The second clause is also misleading, because there is simply no response to wait for. Then the examples just need to be fixed up to use dbus:call instead of dbus:send. The second example uses dbus:send-and-await-reply, which isn't even part of the api. It seems to have a different call form from dbus:call, so we would have to examine that more closely and figure out what the intent was. Thanks, -- John Foerch ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
