this turned into a 'review all the properties in the docs and try to make it consistent' exercise.  I'll have something together even if it's a partial doc fix in the next couple days.

There is an Octave Developer's Meeting tomorrow.  We should probably discuss things a bit more.  My sense is that the release doesn't happen this year, but maybe in January, 2024.

@nrjank: A part of this bug is simply documentation which could be done on the stable branch.  Any desire to finish that part ahead of the 9.1 release, or should we table it for now?

that message is explicit enough it probably removes the need for the Note i was asking about in that diff. 

should other cases of doc_unused be changed to doc_notimpl? In addition to adding windowstate, doc_unused is currently applied to:

Root:
hittest
pickableparts
monitorpositions
pointerlocation
pointerwindow
a list of Root object 'overridden shared properties':
            "beingdeleted", "busyaction", "buttondownfcn", ...
            "clipping", "createfcn", "deletefcn", "handlevisibility", ...
            "hittest", "interruptible", "selected", ...
            "selectionhighlight", "uicontextmenu", "visible"

Figure:
clipping
pickableparts
currentcharacter
dockcontrols

Axes:
clipping
ambientlightcolor
clippingstyle
colororderindex
gridalphamode
gridcolor
gridcolormode
linestyleorder
linestyleorderindex
minorgridalphamode
minorgridcolor
minorgridcolormode
projection
sortmethod
xticklabelrotation
yticklabelrotation
zticklabelrotation

Line:
children

Text:
children
editing

Image:
children

Surface:
children

Patch:
children
interpreter

Scatter:
children

Light:
children

uimenu:
buttondownfcn

uicontextmenu:
buttondownfcn

uitoolbar:
buttondownfcn

uipushtool:
buttondownfcn

uitoggletool:
buttondownfcn


a bunch of those like the root list, 'children', and buttondownfcn fall under 'Overridden shared properties'. not being sure what exactly that implies, should they be noted differently/stay doc_unused?

The number of properties that are accepted, but unimplemented, is rather small and can be handled manually.  Typically there is even a note in the commit message when a property is added that isn't implemented.  What programmers, such as myself, should do is also modify genpropdoc.m at the time of the commit to update that.

I would suggest that instead of using "doc_unused", use "doc_unimpl" which expands to

  doc_notimpl = "%s is not yet implemented for __objname__ objects.  \
__prop__ is unused.";

I don't know how to find the ones that are just placeholders.  Even if you took the list of all properties and examined the output of

for p in $properties; do
  echo "PROPERTY: $p";
  hg locate '*.h' '*.cc' '*.m' | xargs grep -iw $p
done

it would be difficult to determine if a property was unimplemented for one type of graphics object but implemented for another for another (for example, if "color" was implemented for lines but not patches), or to determine if its implementation was incomplete.

okay, the behavior makes sense.  Perhaps we should get in the habit of marking such things as non-functional in the help documentation. Are there other properties we know operate the same way?

As reported over on discourse, attempting to use the 'WindowState' property for figures seems to have no effect, whether during creation or later using the set command.

Tested on Windows with Octave 8.4.0 and 9.0.1 (hg id: 14cb31ec0251), as well as on Ubuntu with 9.0.0 (hg id: 4f09c1b4148).

the following commands all produce a normally sized figure window:

figure (1, "windowstate", "maximized") %new named fig
figure ("windowstate", "maximized") %new fig unnamed
figure (1, "windowstate", "maximized") %new fig into existing fig

similarly:

a = figure;
set (a, "windowstate", "maximized")

fails to change the state of the window.  same behavior for "minimized", and "fullscreen".  Tested on single and multiple monitor setups in case the latter was causing the problem.

can anyone verify if this behavior is a regression or was it always nonfunctional parameter?