bugGNU Octave - Bugs: bug #61681, function documentation should...

 
 

bug #61681: function documentation should always mention output if there is one

Submitter:  Dmitri A. Sergatskov <dasergatskov>
Submitted:  Wed 15 Dec 2021 03:46:38 PM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  3 - Low Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 12 Dec 2022 10:48:05 PM UTC, comment #14: 

I used Perl to find remaining instances where the documentation had no output but the function did.  I fixed those on the stable branch here: http://hg.savannah.gnu.org/hgweb/octave/rev/505ed551e366.

I will remove the list of functions on the wiki.

Rik <rik5>
Group administrator
Sun 11 Dec 2022 02:31:26 PM UTC, comment #13: 

there was a long list of functions over there. rik, did your set of changes get all of those, or does it need verification?

Nicholas Jankowski <nrjank>
Group Member
Sun 11 Dec 2022 12:28:37 PM UTC, comment #12: 

comment #11:

> I checked in two more massive changesets that document an output for every function that produces one.  See
>
> http://hg.savannah.gnu.org/hgweb/octave/rev/5d3faba0342e
> http://hg.savannah.gnu.org/hgweb/octave/rev/32d2b6604a9f
>
> I'm going to close this report as fixed.  Any tweaks or functions I missed can be the subject of a new bug report.
>


This issue is still mentioned on the wiki. Seeing that it's been closed, I think it's safe to remove it from over there, correct?

emilyeclipse
Tue 05 Apr 2022 10:37:29 PM UTC, comment #11: 

I checked in two more massive changesets that document an output for every function that produces one.  See

http://hg.savannah.gnu.org/hgweb/octave/rev/5d3faba0342e
http://hg.savannah.gnu.org/hgweb/octave/rev/32d2b6604a9f

I'm going to close this report as fixed.  Any tweaks or functions I missed can be the subject of a new bug report.

Rik <rik5>
Group administrator
Tue 28 Dec 2021 03:58:02 AM UTC, comment #10: 

I've started on this.  See the following two changesets where I updated the isXXX functions to always return an output and the name of that output is TF (for True/False).

http://hg.savannah.gnu.org/hgweb/octave/rev/83aeaba707d8
http://hg.savannah.gnu.org/hgweb/octave/rev/841a10208c38

Rik <rik5>
Group administrator
Wed 15 Dec 2021 09:35:33 PM UTC, comment #9: 

The C++ files don't use the leading comment characters "##".  This grep command worked for me in libinterp/corefcn.


grep 'deftypefn {} {}' *.cc



Rik <rik5>
Group administrator
Wed 15 Dec 2021 08:12:31 PM UTC, comment #8: 

i did the grep on the entire octave source to get the first list, so maybe it's not quite the same for the C++?

Nicholas Jankowski <nrjank>
Group Member
Wed 15 Dec 2021 07:44:34 PM UTC, comment #7: 

I substracted the list from comment #5 from the list in comment #3.  Result is attached.  There are 285 instances which is large, but manageable.

We should also do the same thing for the libinterp/, libgui/, and src/ directories as there may be functions defined in C++ that have this issue.  Same grep should work though.



(file #52509)

Rik <rik5>
Group administrator
Wed 15 Dec 2021 07:32:57 PM UTC, comment #6: 

sounds good, that'll shorten the task quite a bit

Nicholas Jankowski <nrjank>
Group Member
Wed 15 Dec 2021 07:23:52 PM UTC, comment #5: 

The following functions do not have outputs:
(I also attached the file)

scripts/@ftp/mget.m
scripts/audio/@audioplayer/play.m
scripts/audio/@audioplayer/playblocking.m
scripts/audio/@audiorecorder/record.m
scripts/audio/sound.m
scripts/audio/soundsc.m
scripts/general/celldisp.m
scripts/gui/movegui.m
scripts/gui/rmappdata.m
scripts/gui/setappdata.m
scripts/gui/uiwait.m
scripts/help/doc_cache_create.m
scripts/help/print_usage.m
scripts/image/imwrite.m
scripts/image/movie.m
scripts/image/spinmap.m
scripts/io/csvwrite.m
scripts/io/dlmwrite.m
scripts/java/javaaddpath.m
scripts/java/javarmpath.m
scripts/miscellaneous/citation.m
scripts/miscellaneous/clearvars.m
scripts/miscellaneous/delete.m
scripts/miscellaneous/inputParser.m
scripts/miscellaneous/news.m
scripts/miscellaneous/run.m
scripts/plot/appearance/box.m
scripts/plot/appearance/camlookat.m
scripts/plot/appearance/camorbit.m
scripts/plot/appearance/camroll.m
scripts/plot/appearance/camzoom.m
scripts/plot/appearance/datetick.m
scripts/plot/appearance/grid.m
scripts/plot/appearance/lighting.m
scripts/plot/appearance/shading.m
scripts/plot/appearance/whitebg.m
scripts/plot/draw/comet.m
scripts/plot/draw/comet3.m
scripts/plot/util/cla.m
scripts/plot/util/hgsave.m
scripts/plot/util/hold.m
scripts/plot/util/linkaxes.m
scripts/plot/util/private/__add_default_menu__.m
scripts/plot/util/refresh.m
scripts/plot/util/refreshdata.m
scripts/plot/util/rotate.m
scripts/plot/util/saveas.m
scripts/plot/util/savefig.m
scripts/prefs/addpref.m
scripts/prefs/rmpref.m
scripts/prefs/setpref.m
scripts/profiler/profexplore.m
scripts/profiler/profexport.m
scripts/profiler/profshow.m
scripts/signal/freqz_plot.m
scripts/sparse/etreeplot.m
scripts/sparse/spy.m
scripts/sparse/treeplot.m
scripts/testfun/demo.m
scripts/testfun/oruntests.m
scripts/testfun/private/compare_plot_demos.m
scripts/testfun/private/dump_demos.m
scripts/testfun/private/html_compare_plot_demos.m
scripts/testfun/rundemos.m
scripts/testfun/__debug_octave__.m


If there is not objection, I can delete those from Wiki.

Dmitri.
--


(file #52508)

Dmitri A. Sergatskov <dasergatskov>
Wed 15 Dec 2021 06:11:53 PM UTC, comment #4: 
Nicholas Jankowski <nrjank>
Group Member
Wed 15 Dec 2021 04:58:43 PM UTC, comment #3: 

ok, i did a

grep -r "## -*- texinfo -*-
## @deftypefn  {} {}" *

(newbie isn't sure what character to use for a linebreak in there)

generated the following list:

examples/code/@FIRfilter/FIRfilter.m:
examples/code/@FIRfilter/FIRfilter_aggregation.m:
examples/code/@polynomial/polynomial.m:
examples/code/@polynomial/polynomial_superiorto.m:
scripts/@ftp/cd.m:
scripts/@ftp/mget.m:
scripts/audio/@audioplayer/play.m:
scripts/audio/@audioplayer/playblocking.m:
scripts/audio/@audioplayer/set.m:
scripts/audio/@audiorecorder/record.m:
scripts/audio/@audiorecorder/set.m:
scripts/audio/record.m:
scripts/audio/sound.m:
scripts/audio/soundsc.m:
scripts/general/accumarray.m:
scripts/general/celldisp.m:
scripts/general/cplxpair.m:
scripts/general/dblquad.m:
scripts/general/flip.m:
scripts/general/interpft.m:
scripts/general/logspace.m:
scripts/general/num2str.m:
scripts/general/polyarea.m:
scripts/general/postpad.m:
scripts/general/prepad.m:
scripts/general/randi.m:
scripts/general/repmat.m:
scripts/general/rng.m:
scripts/general/rot90.m:
scripts/general/rotdim.m:
scripts/general/shift.m:
scripts/general/structfun.m:
scripts/general/triplequad.m:
scripts/geometry/voronoi.m:
scripts/gui/errordlg.m:
scripts/gui/helpdlg.m:
scripts/gui/movegui.m:
scripts/gui/rmappdata.m:
scripts/gui/setappdata.m:
scripts/gui/uipanel.m:
scripts/gui/uipushtool.m:
scripts/gui/uitoggletool.m:
scripts/gui/uitoolbar.m:
scripts/gui/uiwait.m:
scripts/gui/waitforbuttonpress.m:
scripts/gui/warndlg.m:
scripts/help/doc.m:
scripts/help/doc_cache_create.m:
scripts/help/help.m:
scripts/help/lookfor.m:
scripts/help/print_usage.m:
scripts/help/type.m:
scripts/image/im2double.m:
scripts/image/im2frame.m:
scripts/image/image.m:
scripts/image/imagesc.m:
scripts/image/imformats.m:
scripts/image/imshow.m:
scripts/image/imwrite.m:
scripts/image/movie.m:
scripts/image/rgbplot.m:
scripts/image/spinmap.m:
scripts/io/csvwrite.m:
scripts/io/dlmwrite.m:
scripts/java/javaaddpath.m:
scripts/java/javachk.m:
scripts/java/javaclasspath.m:
scripts/java/javamem.m:
scripts/java/javarmpath.m:
scripts/legacy/@inline/inline.m:
scripts/legacy/findstr.m:
scripts/legacy/flipdim.m:
scripts/legacy/strmatch.m:
scripts/linear-algebra/cond.m:
scripts/linear-algebra/cross.m:
scripts/linear-algebra/isdefinite.m:
scripts/linear-algebra/ishermitian.m:
scripts/linear-algebra/issymmetric.m:
scripts/linear-algebra/orth.m:
scripts/linear-algebra/rank.m:
scripts/linear-algebra/rref.m:
scripts/miscellaneous/bunzip2.m:
scripts/miscellaneous/cast.m:
scripts/miscellaneous/citation.m:
scripts/miscellaneous/clearvars.m:
scripts/miscellaneous/computer.m:
scripts/miscellaneous/copyfile.m:
scripts/miscellaneous/delete.m:
scripts/miscellaneous/dir.m:
scripts/miscellaneous/dos.m:
scripts/miscellaneous/edit.m:
scripts/miscellaneous/fileattrib.m:
scripts/miscellaneous/grabcode.m:
scripts/miscellaneous/gunzip.m:
scripts/miscellaneous/inputname.m:
scripts/miscellaneous/inputParser.m:
scripts/miscellaneous/inputParser.m:
scripts/miscellaneous/inputParser.m:
scripts/miscellaneous/inputParser.m:
scripts/miscellaneous/isfolder.m:
scripts/miscellaneous/ismethod.m:
scripts/miscellaneous/license.m:
scripts/miscellaneous/list_primes.m:
scripts/miscellaneous/ls.m:
scripts/miscellaneous/memory.m:
scripts/miscellaneous/methods.m:
scripts/miscellaneous/mex.m:
scripts/miscellaneous/mkdir.m:
scripts/miscellaneous/mkoctfile.m:
scripts/miscellaneous/movefile.m:
scripts/miscellaneous/nargoutchk.m:
scripts/miscellaneous/news.m:
scripts/miscellaneous/nthargout.m:
scripts/miscellaneous/open.m:
scripts/miscellaneous/publish.m:
scripts/miscellaneous/run.m:
scripts/miscellaneous/unix.m:
scripts/miscellaneous/untar.m:
scripts/miscellaneous/unzip.m:
scripts/miscellaneous/validateattributes.m:
scripts/miscellaneous/ver.m:
scripts/miscellaneous/what.m:
scripts/optimization/fminunc.m:
scripts/optimization/fsolve.m:
scripts/optimization/fzero.m:
scripts/optimization/optimget.m:
scripts/optimization/optimset.m:
scripts/path/import.m:
scripts/path/savepath.m:
scripts/pkg/pkg.m:
scripts/plot/appearance/annotation.m:
scripts/plot/appearance/axis.m:
scripts/plot/appearance/box.m:
scripts/plot/appearance/camlookat.m:
scripts/plot/appearance/camorbit.m:
scripts/plot/appearance/camroll.m:
scripts/plot/appearance/camzoom.m:
scripts/plot/appearance/caxis.m:
scripts/plot/appearance/clabel.m:
scripts/plot/appearance/datetick.m:
scripts/plot/appearance/grid.m:
scripts/plot/appearance/gtext.m:
scripts/plot/appearance/hidden.m:
scripts/plot/appearance/legend.m:
scripts/plot/appearance/lighting.m:
scripts/plot/appearance/material.m:
scripts/plot/appearance/orient.m:
scripts/plot/appearance/private/__gnuplot_legend__.m:
scripts/plot/appearance/shading.m:
scripts/plot/appearance/specular.m:
scripts/plot/appearance/text.m:
scripts/plot/appearance/title.m:
scripts/plot/appearance/view.m:
scripts/plot/appearance/whitebg.m:
scripts/plot/appearance/xlabel.m:
scripts/plot/appearance/ylabel.m:
scripts/plot/appearance/zlabel.m:
scripts/plot/draw/area.m:
scripts/plot/draw/bar.m:
scripts/plot/draw/barh.m:
scripts/plot/draw/camlight.m:
scripts/plot/draw/colorbar.m:
scripts/plot/draw/comet.m:
scripts/plot/draw/comet3.m:
scripts/plot/draw/compass.m:
scripts/plot/draw/contour.m:
scripts/plot/draw/contour3.m:
scripts/plot/draw/contourf.m:
scripts/plot/draw/cylinder.m:
scripts/plot/draw/ellipsoid.m:
scripts/plot/draw/errorbar.m:
scripts/plot/draw/ezcontour.m:
scripts/plot/draw/ezcontourf.m:
scripts/plot/draw/ezmesh.m:
scripts/plot/draw/ezmeshc.m:
scripts/plot/draw/ezplot.m:
scripts/plot/draw/ezplot3.m:
scripts/plot/draw/ezpolar.m:
scripts/plot/draw/ezsurf.m:
scripts/plot/draw/ezsurfc.m:
scripts/plot/draw/feather.m:
scripts/plot/draw/fill.m:
scripts/plot/draw/fill3.m:
scripts/plot/draw/fplot.m:
scripts/plot/draw/hist.m:
scripts/plot/draw/light.m:
scripts/plot/draw/lightangle.m:
scripts/plot/draw/line.m:
scripts/plot/draw/loglog.m:
scripts/plot/draw/loglogerr.m:
scripts/plot/draw/mesh.m:
scripts/plot/draw/meshc.m:
scripts/plot/draw/meshz.m:
scripts/plot/draw/ostreamtube.m:
scripts/plot/draw/pareto.m:
scripts/plot/draw/patch.m:
scripts/plot/draw/pcolor.m:
scripts/plot/draw/peaks.m:
scripts/plot/draw/pie.m:
scripts/plot/draw/pie3.m:
scripts/plot/draw/plot.m:
scripts/plot/draw/plot3.m:
scripts/plot/draw/plotmatrix.m:
scripts/plot/draw/plotyy.m:
scripts/plot/draw/polar.m:
scripts/plot/draw/quiver.m:
scripts/plot/draw/quiver3.m:
scripts/plot/draw/rectangle.m:
scripts/plot/draw/ribbon.m:
scripts/plot/draw/rose.m:
scripts/plot/draw/scatter.m:
scripts/plot/draw/scatter3.m:
scripts/plot/draw/semilogx.m:
scripts/plot/draw/semilogxerr.m:
scripts/plot/draw/semilogy.m:
scripts/plot/draw/semilogyerr.m:
scripts/plot/draw/shrinkfaces.m:
scripts/plot/draw/slice.m:
scripts/plot/draw/sombrero.m:
scripts/plot/draw/sphere.m:
scripts/plot/draw/stairs.m:
scripts/plot/draw/stem.m:
scripts/plot/draw/stem3.m:
scripts/plot/draw/stemleaf.m:
scripts/plot/draw/streamline.m:
scripts/plot/draw/streamribbon.m:
scripts/plot/draw/streamtube.m:
scripts/plot/draw/surf.m:
scripts/plot/draw/surface.m:
scripts/plot/draw/surfc.m:
scripts/plot/draw/surfl.m:
scripts/plot/draw/surfnorm.m:
scripts/plot/draw/tetramesh.m:
scripts/plot/draw/trimesh.m:
scripts/plot/draw/triplot.m:
scripts/plot/draw/trisurf.m:
scripts/plot/draw/waterfall.m:
scripts/plot/util/axes.m:
scripts/plot/util/cla.m:
scripts/plot/util/clf.m:
scripts/plot/util/close.m:
scripts/plot/util/figure.m:
scripts/plot/util/hggroup.m:
scripts/plot/util/hgsave.m:
scripts/plot/util/hold.m:
scripts/plot/util/isgraphics.m:
scripts/plot/util/ishold.m:
scripts/plot/util/linkaxes.m:
scripts/plot/util/newplot.m:
scripts/plot/util/openfig.m:
scripts/plot/util/pan.m:
scripts/plot/util/print.m:
scripts/plot/util/printd.m:
scripts/plot/util/private/__add_default_menu__.m:
scripts/plot/util/refresh.m:
scripts/plot/util/refreshdata.m:
scripts/plot/util/rotate.m:
scripts/plot/util/rotate3d.m:
scripts/plot/util/saveas.m:
scripts/plot/util/savefig.m:
scripts/plot/util/subplot.m:
scripts/plot/util/zoom.m:
scripts/plot/util/__actual_axis_position__.m:
scripts/plot/util/__opengl_info__.m:
scripts/polynomial/conv.m:
scripts/polynomial/poly.m:
scripts/polynomial/polyder.m:
scripts/polynomial/polyint.m:
scripts/polynomial/polyout.m:
scripts/prefs/addpref.m:
scripts/prefs/ispref.m:
scripts/prefs/prefdir.m:
scripts/prefs/rmpref.m:
scripts/prefs/setpref.m:
scripts/profiler/profexplore.m:
scripts/profiler/profexport.m:
scripts/profiler/profile.m:
scripts/profiler/profshow.m:
scripts/set/powerset.m:
scripts/set/unique.m:
scripts/signal/blackman.m:
scripts/signal/fftconv.m:
scripts/signal/fftfilt.m:
scripts/signal/fftshift.m:
scripts/signal/freqz_plot.m:
scripts/signal/hamming.m:
scripts/signal/hanning.m:
scripts/signal/ifftshift.m:
scripts/signal/spectral_adf.m:
scripts/signal/spectral_xdf.m:
scripts/sparse/etreeplot.m:
scripts/sparse/gplot.m:
scripts/sparse/ilu.m:
scripts/sparse/private/__sprand__.m:
scripts/sparse/sprand.m:
scripts/sparse/sprandn.m:
scripts/sparse/sprandsym.m:
scripts/sparse/spy.m:
scripts/sparse/treelayout.m:
scripts/sparse/treeplot.m:
scripts/specfun/betainc.m:
scripts/specfun/betaincinv.m:
scripts/specfun/gammainc.m:
scripts/specfun/gammaincinv.m:
scripts/specfun/lcm.m:
scripts/specfun/pow2.m:
scripts/special-matrix/gallery.m:
scripts/special-matrix/hankel.m:
scripts/special-matrix/pascal.m:
scripts/special-matrix/toeplitz.m:
scripts/special-matrix/vander.m:
scripts/statistics/center.m:
scripts/statistics/corr.m:
scripts/statistics/cov.m:
scripts/statistics/discrete_rnd.m:
scripts/statistics/empirical_rnd.m:
scripts/statistics/kendall.m:
scripts/statistics/kurtosis.m:
scripts/statistics/mad.m:
scripts/statistics/mean.m:
scripts/statistics/meansq.m:
scripts/statistics/median.m:
scripts/statistics/mode.m:
scripts/statistics/moment.m:
scripts/statistics/range.m:
scripts/statistics/ranks.m:
scripts/statistics/run_count.m:
scripts/statistics/skewness.m:
scripts/statistics/spearman.m:
scripts/statistics/statistics.m:
scripts/statistics/std.m:
scripts/statistics/var.m:
scripts/strings/dec2base.m:
scripts/strings/dec2bin.m:
scripts/strings/dec2hex.m:
scripts/strings/index.m:
scripts/strings/strjust.m:
scripts/strings/substr.m:
scripts/strings/untabify.m:
scripts/testfun/assert.m:
scripts/testfun/demo.m:
scripts/testfun/example.m:
scripts/testfun/fail.m:
scripts/testfun/oruntests.m:
scripts/testfun/private/compare_plot_demos.m:
scripts/testfun/private/dump_demos.m:
scripts/testfun/private/html_compare_plot_demos.m:
scripts/testfun/rundemos.m:
scripts/testfun/speed.m:
scripts/testfun/test.m:
scripts/testfun/__debug_octave__.m:
scripts/testfun/__run_test_suite__.m:
scripts/time/is_leap_year.m:


maybe that should be added to a wiki page so it can be checked off as they're fixed?

Nicholas Jankowski <nrjank>
Group Member
Wed 15 Dec 2021 04:48:23 PM UTC, comment #2: 

is there an easy way to parse core octave to generate a list of functions potentially needing this change?

seems most would start with:

## -*- texinfo -*-
## @deftypefn  {} {}


Nicholas Jankowski <nrjank>
Group Member
Wed 15 Dec 2021 04:31:50 PM UTC, comment #1: 

I brought up this issue somewhere recently; maybe it was on Discourse.  Many newbies to Octave don't understand that functions typically produce an output even if it isn't stated.  For example, "help sind" starts with just "sind (X)" and doesn't mention an output because it is understood.

I proposed that we be explicit, as Matlab does, and always list the output when there is one.  So sind.m would become "Y = sind (X)".

fftfilt() is just another example of this general issue.  I think we should do it, but it is a lot of work which is why it hasn't taken place yet.

Rik <rik5>
Group administrator
Wed 15 Dec 2021 03:46:38 PM UTC, original submission:  

help fftfilt does not mention that it returns the matrix.
That could be interpreted that it does filtering in-place.
This applies both to 7.x and dev version.

Dmitri.
--

Dmitri A. Sergatskov <dasergatskov>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #52509:  need_doc_output.txt added by rik5 (8KiB - text/plain)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by emilyeclipse (Posted a comment)
  • -email is unavailable- added by nrjank (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by dasergatskov (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-04-05 rik5 StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2021-12-28 rik5 StatusConfirmed In Progress
    2021-12-15 rik5 Attached File- Added need_doc_output.txt, #52509
    2021-12-15 dasergatskov Attached File- Added octave_no_output.txt, #52508
    2021-12-15 rik5 Severity3 - Normal 1 - Wish
        Priority5 - Normal 3 - Low
        StatusNone Confirmed
        Summary&quot;help fftfilt&quot; does not mention output function documentation should always mention output if there is one

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code