[Oorexx-bugs] [ oorexx-Documentation-1824162 ] lack of examples

[SourceForge.net <no...@so...>]

Documentation item #1824162, was opened at 2007-11-01 16:36
Message generated for change (Comment added) made by hagrinas
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=1001880&aid=1824162&group_id=119701

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Reference
Group: 3.2.0
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Hagrinas (hagrinas)
Assigned to: Nobody/Anonymous (nobody)
Summary: lack of examples

Initial Comment:
10/25/07 version.

The reference and programming guide are devoid of examples using appendall. 

The reference and programming guide are devoid of examples using the properties class. 

Utility class: 
The comparator class objects and the rexxqueue object lack examples in both of those documents.

The readme release notes are still for 3.1.2. It mentions a CHANGES document, which is not in the ooRexx-3.2.0-all.zip, and will be particularly useful for this release given the number of significant improvements.

The use of some of these is more obvious than for others, but the documentation in these areas is inconsistent with the rest of the documentation and with previous versions of these documents. 


----------------------------------------------------------------------

>Comment By: Hagrinas (hagrinas)
Date: 2007-11-02 23:54

Message:
Logged In: YES 
user_id=1796550
Originator: YES

Thanks.  The properties.rex example is clear.  Aside from wanting it
clarified, I also wanted to report things before the release, so these
would be known issues before then. Sorry for lumping them all together.

Some are unlikely to confuse anybody, even without examples, but I
mentioned them for consistency. The readme and changes are clearly more
important.  If README mentioned the properties.rex as an example, it would
be less of an immediate concern. 

For appendall, I would recommend making b into a stem variable, since it
would show how to go from stems to an array.  

I would also suggest creating the stem variables from an array using
putall, and I would point out that putall also lacks any examples, but I
don't want to further complicate this with yet one more item that should be
in a different tracker, so I won't mention it. But if I did make such a
suggestion, I would mention that putall could also be very handy in the
oodialog reference in places where stems are required, since data is often
in other collection classes. Sorry. 

----------------------------------------------------------------------

Comment By: pragmatic_lee (pragmatic_lee)
Date: 2007-11-02 14:16

Message:
Logged In: YES 
user_id=1223125
Originator: NO

Since there a 6 different items listed in this one tracker. Guess we need
to add (as comments) each "fix" until all items have been addressed.  

appendAll example:

a = .array~of('Rick','David','Rony','MarkH','MarkM')
say a~items  --> Yields 5

b = .array~of('Tom','Dick','Harry')
a~appendAll(b)
say a~items  --> Yields 8

c = .set~of('Larry','Joe','Pam')
a~appendAll(c)
say a~items  --> Yields 11

do i over a
  say i
end
/* Possible Results (a Set is not an ordered collection, so order of
results may vary)
Rick
David
Rony
MarkH
MarkM
Tom
Dick
Harry
Joe
Pam
Larry
*/

Properties Class example:
  

Comparator Class example:


RexxQueue example:


Readme update:
  David, this probably should be handled by you.


CHANGES document:
  David, this probably should be handled by you.



----------------------------------------------------------------------

Comment By: pragmatic_lee (pragmatic_lee)
Date: 2007-11-01 23:44

Message:
Logged In: YES 
user_id=1223125
Originator: NO

Hagrinas,
In regards to the properties class, you can find a sample program in
"samples" root folder.  It is named "properties.rex".  Maybe this will hold
you over till more work can be done on the documentation.

Lee

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=1001880&aid=1824162&group_id=119701