Bug #6497 for Net-OSCAR: documentation errors

Thu Jun 03 00:23:27 2004 Guest - Ticket created

Subject:

documentation errors

Net::OSCAR 1.11, running on Perl 5.8.2 on Windows 2000 using cygwin. I found two things in the doc that seem to be inconsistent with the implementation: 1. set_away() needs an argument of a null string to clear the "away" status. undef doesn't seem to do it. 2. set_info() seems to take immediate action and not require commit_buddylist(). Thanks! Great stuff! --Tom Porcher

Wed Jun 09 01:07:31 2004 matthewg [...] zevils.com - Correspondence added

[guest - Thu Jun 3 00:23:27 2004]: Show quoted text

> Net::OSCAR 1.11, running on Perl 5.8.2 on Windows 2000 using cygwin. > > I found two things in the doc that seem to be inconsistent with the > implementation: > > 1. set_away() needs an argument of a null string to clear the "away" > status. undef doesn't seem to do it.

Fixed in CVS, thanks! Show quoted text

> 2. set_info() seems to take immediate action and not require > commit_buddylist().

According to the documentation, '[set_info] Sets the user's profile. Call "commit_buddylist" to have the new profile stored on the OSCAR server.' Ah, I see the problem, "stored on the OSCAR server" means different things to me and people-other-than-me, I'll change that to "saved into the buddylist, so that it will be set the next time the screenname is signed on. (This is a Net::OSCAR-specific feature, so other clients will not pick up the profile from the buddylist.)" Hrm, that new wording is fairly unwieldy, what do you think?

Wed Jun 09 01:07:32 2004 matthewg [...] zevils.com - Status changed from 'new' to 'resolved'

Wed Jun 09 01:07:32 2004 matthewg [...] zevils.com - Given to MATTHEWG

Wed Jun 16 11:38:25 2004 Guest - Correspondence added

From:

Tom Porcher

Show quoted text

> Hrm, that new wording is fairly unwieldy, what do you think?

Reading your explanation and the paragraph that follows under set_info() makes this clear. I think the problem I had was that this method sounded just like the other functions that require commit_buddylist(). Here's a stab at the wording for this section: ------------------- set_info (PROFILE) Sets the user's current profile. This also sets the profile in the local buddylist. Call "commit_buddylist" to have the new profile stored on the OSCAR server. Note that Net::OSCAR stores the user's profile in the server-side buddylist, and so this method will not have to be called every time the user signs on using Net::OSCAR. However, other clients do not store the profile on the server. This method will need to be called to set the user's profile if it was previously set with a non-Net::OSCAR-based client. -------------------- I hope some part of this is useful. BTW, another doc nit: * The awaymsg and profile members of the hashref returned by buddy_in() are not specified under buddy(). The description should state that these members will only be present if get_away() or get_info() has been called (is this true?). Thanks! --Tom Porcher (porcher@acm.org) --Tom

Wed Jun 16 11:38:27 2004 The RT System itself - Status changed from 'resolved' to 'open'

Wed Jun 16 11:58:50 2004 Guest - Correspondence added

From:

Tom Porcher

Show quoted text

> BTW, another doc nit: > * The awaymsg and profile members of the hashref returned by > buddy_in() > are not specified under buddy(). The description should state that > these members will only be present if get_away() or get_info() has > been > called (is this true?).

Oops. These members *are* documented under buddy_info(). I was confused between the callbacks "buddy_in()" and "buddy_info()". Sorry!!! [maybe buddy_info() might be called user_info() since it is only in response to get_away(WHO) or get_info(WHO), BTJWUTD] --Tom

Wed Jul 07 03:24:21 2004 matthewg [...] zevils.com - Correspondence added

[guest - Wed Jun 16 11:38:25 2004]: Show quoted text

> Reading your explanation and the paragraph that follows under > set_info() > makes this clear. I think the problem I had was that this method > sounded just like the other functions that require commit_buddylist(). > Here's a stab at the wording for this section:

And here's another one: =item set_info (PROFILE) Sets the user's profile. Call L<"commit_buddylist"> to have the new profile saved into the buddylist, so that it will be set the next time the screenname is signed on. (This is a Net::OSCAR-specific feature, so other clients will not pick up the profile from the buddylist.) Note that Net::OSCAR stores the user's profile in the server-side buddylist, so if L<"commit_buddylist"> is called after setting the profile with this method, the user will automatically get that same profile set whenever they sign on through Net::OSCAR. See the file C<PROTOCOL>, included with the C<Net::OSCAR> distribution, for details of how we're storing this data.

Wed Jul 07 03:45:04 2004 matthewg [...] zevils.com - Correspondence added

[guest - Wed Jun 16 11:58:50 2004]: Show quoted text

> Sorry!!! [maybe buddy_info() might be called user_info() since it is > only in response to get_away(WHO) or get_info(WHO), BTJWUTD]

I'm considering reorganizing things a bit for the 2.0 release which I'm currently pushing towards. There might be a new class, Net::OSCAR::User, which has methods which return the various data. How would you feel about something like: # Get a user from the buddylist $buddylist = $oscar->buddylist(); $somedude = $buddylist->group("Buddies")->user("somedude"); if(time() - $somedude->info_timestamp() > 300) { $somedude->fetch_info(); } else { callback_got_user_info($oscar, $somedude); } # Get a random user $otherdude = $oscar->get_user("otherdude"); $otherdude->fetch_info(); # Perhaps we can even do things like: $somedude->send_im("hi") #...but the existing way still works.

Thu Aug 19 03:47:18 2004 matthewg [...] zevils.com - Status changed from 'open' to 'resolved'