bugGNU Octave - Bugs: bug #51997, Missing documentation of return...

 
 

bug #51997: Missing documentation of return value of warning()

Submitted by:  Ernst Reissner <ernstreissner>
Submitted on:  Tue 12 Sep 2017 08:59:05 AM UTC  
 
Category: DocumentationSeverity: 3 - Normal
Priority: 5 - NormalItem Group: Documentation
Status: FixedAssigned to: None
Originator Name: ernstreissnerOpen/Closed: Closed
Release: devOperating System: Any

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission Jump to the original submission)

Fri 15 Sep 2017 08:56:03 PM UTC, comment #6:

I made a few tweaks to the documentation on top of the ones from Pantxo and checked in the cset here http://hg.savannah.gnu.org/hgweb/octave/rev/9c198d1c84cd.

Marking as fixed. Closing report.

Rik <rik5>
Project Administrator
Thu 14 Sep 2017 01:41:18 PM UTC, comment #5:

@Markus: thanks for testing (and fixing the test :-))

@Rik:

>> From the results in comment #3, it seems Octave is Matlab compatible


No, Octave currently always return all warnings, not only those that are being changed, except when "query" is used.

I attached a second take of the patch, with the above fixed, associated BIST, and the "on", "off" ... states back in the header.

(file #41802)

Pantxo Diribarne <pantxo>
Project Member
Wed 13 Sep 2017 11:21:52 PM UTC, comment #4:

From the results in comment #3, it seems Octave is Matlab compatible.

In terms of updating the documentation, I would prefer to see the explicit forms,

rather than just

with an explanation of state deeper in the documentation. Most people reading the documentation are trying to figure out how to use the function with the minimum amount of research necessary. If you provide the standard calling forms in the function summary it is often unnecessary to read any further which is quite helpful.

Rik <rik5>
Project Administrator
Wed 13 Sep 2017 04:15:58 PM UTC, comment #3:

Below the results in Matlab R2016a:

"loglog (0:10)" does not issue a warning in Matlab, "loglog (-1:10)" does. Thus, I used that in the test.

Markus Mützel <mmuetzel>
Project Member
Wed 13 Sep 2017 03:37:58 PM UTC, comment #2:

I tried to rewrite the documentation (see attached patch) but then found that Octave behaved strangely, or at least not as ML says it behaves in the documentation, with regard to output warnstruct.

So I have to requests:

  • Can someone take a look at the modified doc and tell me if it is clearer or worse ?
  • Can someone run the following tests in Matlab to determine how Octave should strive to behave?

(file #41794)

Pantxo Diribarne <pantxo>
Project Member
Wed 13 Sep 2017 01:12:01 PM UTC, comment #1:

The old title was very misleading, I hope this one is better suited.

To my knowledge, the old warning state gets returned as a struct. If that was all the truth, the documentation can easily be fixed.

Kai Torben Ohlhus <siko1056>
Project Member
Tue 12 Sep 2017 08:59:05 AM UTC, original submission:

help warning yields

which means that querying does not yield a return value.
This is not true, which is illustrated by the following.

Ernst Reissner <ernstreissner>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

Attached Files
file #41802:  warndoc2.patch added by pantxo (8KiB - text/x-patch)
file #41794:  warndoc.patch added by pantxo (6KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by rik5 (Posted a comment)
  • -unavailable- added by mmuetzel (Posted a comment)
  • -unavailable- added by pantxo (Updated the item)
  • -unavailable- added by siko1056 (Posted a comment)
  • -unavailable- added by siko1056 (Knows best.)
  • -unavailable- added by ernstreissner (Submitted the item)
  • -unavailable- added by ernstreissner
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    Follow 9 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Fri 15 Sep 2017 08:56:03 PM UTCrik5StatusPatch Submitted=>Fixed
      Open/ClosedOpen=>Closed
    Thu 14 Sep 2017 01:41:18 PM UTCpantxoAttached File-=>Added warndoc2.patch, #41802
      StatusConfirmed=>Patch Submitted
    Wed 13 Sep 2017 03:37:58 PM UTCpantxoAttached File-=>Added warndoc.patch, #41794
    Wed 13 Sep 2017 01:12:01 PM UTCsiko1056StatusNone=>Confirmed
      Summaryfunction warning: return value =>Missing documentation of return value of warning()
      Carbon-Copy-=>Added jwe
    Tue 12 Sep 2017 08:59:05 AM UTCernstreissnerCarbon-Copy-=>Added -unavailable-

    Back to the top


    Powered by Savane 3.1-cleanup1