#52 lack of examples

4.0.0
closed
Mark Miesfeld
Reference (110)
5
2012-08-14
2007-11-01
Hagrinas
No

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.

Discussion

  • Lee Peedin
    Lee Peedin
    2007-11-01

    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

     
  • Lee Peedin
    Lee Peedin
    2007-11-02

    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.

     
  • Hagrinas
    Hagrinas
    2007-11-02

    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.

     
  • Hagrinas
    Hagrinas
    2007-11-02

    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.

     
  • Mark Miesfeld
    Mark Miesfeld
    2009-04-07

    Committed revision 4346.

    The primary things "wrong" here are the readme file not being updated and some direction on where the CHANGES file is. That is fixed for the 4.0.0 release, both by the 4346 commit and some previous commits.

    The CHANGES file is not part of the documentation source, it is part of the interpreter source. It is accessible by using the 'Notes' icon on the download page. The file is distributed with the Windows installation and of course with the source code. The readme.pdf now points to the location of the CHANGES file when it mentions it.

    In regards to examples in the doc itself. That's a matter of opinion. I don't think any of the committers feel every single method of every single class needs an example. If there are specific areas where someone needs an example to be able to use the method, function, etc., there are a number of resources where a user can get help. These resources are listed in all the pdf doc files. (In the html versions also.) Of course, we always welcome patches to update the docs if you see a place where an example would be of great benefit to all.

     


Anonymous


Cancel   Add attachments