Skip to content

SciJava Ops descriptions output is confusing, can we improve it? #146

Closed
scijava/incubator
#100

Description

@elevans

Suppose I'm a new user and I have never used the Gaussian filter op. If we get the op description of filter.gauss we get:

> print(ops.descriptions("filter.gauss"))
[filter.gauss(
	 Inputs:
		net.imglib2.RandomAccessibleInterval<I> input1
		double[] input2
		net.imglib2.outofbounds.OutOfBoundsFactory<I, net.imglib2.RandomAccessibleInterval<I>> input3?
	 Containers (I/O):
		net.imglib2.RandomAccessibleInterval<O> container1
)
, filter.gauss(
	 Inputs:
		net.imglib2.RandomAccessibleInterval<I> input1
		double[] input2
	 Containers (I/O):
		net.imglib2.RandomAccessibleInterval<O> container1
)
, filter.gauss(
	 Inputs:
		net.imglib2.RandomAccessibleInterval<I> input1
		java.lang.Double input2
		net.imglib2.outofbounds.OutOfBoundsFactory<I, net.imglib2.RandomAccessibleInterval<I>> input3?
	 Containers (I/O):
		net.imglib2.RandomAccessibleInterval<O> container1
)
, filter.gauss(
	 Inputs:
		net.imglib2.RandomAccessibleInterval<I> input1
		java.lang.Double input2
	 Containers (I/O):
		net.imglib2.RandomAccessibleInterval<O> container1
)
]

Hypothetical user questions:

  • What are Containers (I/O) in this context?
  • The first two filter.gauss entries accept a Double [] while the last two only accept a single Double. Whats the difference? (Is it possible to add a docstring like description to the ops.descriptions() output?).
  • Are all these parameters required? (I know the "?" signifies that the OutOfBoundFactory is optional, but I think we need something more obvious...can't we just add [optional] to the op's description unicode output?)

Things I like about the output:
I think the spacing of the output from ops.descriptions is great. I like the indent scheme, it helped my eyes navigate what is usually a mess.

Activity

  1. ctrueden commented on Oct 24, 2023

    @ctrueden
    Member

    (I know the "?" signifies that the OutOfBoundFactory is optional, but I think we need something more obvious...can't we just add [optional] to the op's description unicode output?)

    More and more I think we need more than one output mode: at least two, like "short" and "full" or some such. Seeing the fully qualified class names annoys me, and seeing "[Optional]" would also annoy me.

    (Is it possible to add a docstring like description to the ops.descriptions() output?).

    I heartily agree with this suggestion. Maybe we could model the "full" mode after Python's help presentation a bit more?

    Speaking of which, I really think there should be a function ops.help which presents the information in this way. It is a much friendlier name than descriptions. I would rename descriptions to list actually, since that's what it's doing: giving a list of ops. And it could return an OpList object which implements List<OpInfo>, and which stringifies nicely—it could even have methods like help() and help(boolean shortMode) to control details of the stringification. I would actually put these help methods on the OpInfo interface itself, and then make OpList just loop its OpInfo objects to generate a concatenated string.

  2. ctrueden commented on Oct 24, 2023

    @ctrueden
    Member

    Relatedly: @tpietzsch expressed the desire to query the ops system for candidate matches, without necessarily invoking all the fancier subsystems like adaptation and simplification. The hints mechanism should help with this, but it makes me think that a really good place for this list/help functionality would be as methods of the op builder classes. Being able to obtain an OpList from a partially or fully built query would be really nice.

  3. self-assigned this
    on Nov 14, 2023
  4. added this to the 1.0.0 milestone on Nov 14, 2023
  5. removed their assignment
    on Nov 14, 2023
  6. gselzer commented on Nov 28, 2023

    @gselzer
    Member

    @elevans with scijava/incubator#95 merged, what else do you want to see here?

  7. elevans commented on Nov 29, 2023

    @elevans
    MemberAuthor

    @gselzer scijava/incubator#95 is great! I think you addressed all my concerns with regard to finding ops. My remaining point that needs to be addressed is if we can improve how we present an optional parameter. While I think the ? works, I'm afraid its not obvious enough to potential users. Just to be clear, this is not a hill I'm willing to die on. But I'd like your thoughts on it.

  8. hinerm commented on Nov 29, 2023

    @hinerm
    Member

    While I think the ? works, I'm afraid its not obvious enough to potential users.

    @elevans @gselzer How do you feel about parentheticals?

    math.divide(Number, Number, [Number])
    
  9. added a commit that references this issue on Dec 13, 2023
  10. added a commit that references this issue on May 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions