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

 
 

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

Submitted by:  Dmitri A. Sergatskov <dasergatskov>
Submitted on:  Wed 15 Dec 2021 03:46:38 PM UTC  
 
Category:  Documentation Severity:  1 - Wish
Priority:  3 - Low Item Group:  Documentation
Status:  In Progress Assigned to:  None
Originator Name:  Open/Closed:  Open
Release:  dev Operating 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)

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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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 nrjank (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by dasergatskov (Submitted the item)
  •  

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

    Only project members can vote.

     

     

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    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"help fftfilt" does not mention output => function documentation should always mention output if there is one

    Back to the top


    Powered by Savane 3.7