Nicer formatting for missing arguments

[ianhi]

This is an awesome project :)

I just started applying it (mpl-extensions/mpl-interactions#168) after I saw your PR to napari. An overall the experience has been great. One potential improvement would be to make the formatting of the warning for missing parameters nicer:
currently it looks like this:

And the majority of space is devoted to ~/mambaforge/envs/mpl-inter/lib/python3.9/site-packages/velin/ref.py:513 in | which isn't super important information for fixing my missing arguments (of which there are shockingly many 😢 edit: turns out in part because I document several kwargs that are passed through to matplotlib. Though that's probably not very numpydocy... ) It would be awesome if this instead had a hierarchical organization. Something like:

filename
   Function 1
       missing

   Function 2 
      missing
      extra

[ianhi]

It also seems that each function has it's warning printed twice, and for several they have set() for their extra which seems incorrect?

I hope this is helpful, happy to try to debug a bit

[Carreau]

Thanks for the kind words !

And, sorry, most of thos print statements are for debug, i'm using there to quickly open the file and line number of the print statement. In the long term, I want to collect all the missing/extra arguments and give an option for the user to automatically insert them with a "TODO", or even let them quickly write the description / type.

But yes, I should that that behind a "verbose" fag at least :-)

[keewis]

it somewhat difficult to know which function the warning refers to: only the module and function name are given, but it would be really useful to also include the line number.

Also, in the case of a module with multiple classes and a shared method name (e.g. __init__) the warning refers to something like module.py:__init__ (which is less than ideal).

[keewis]

looking into it, the duplicated messages happens because compute_new_doc is called twice, and the reporting happens in there:

velin/velin/ref.py

Lines 802 to 824 in 1be3565

	new_doc, d_, jump_to_loc = compute_new_doc(
	docstring,
	filename,
	level=nindent,
	compact=compact,
	meta=meta,
	func_name=func_name,
	config=config,
	)
	if jump_to_loc:
	print("mvim", f"+{start}", filename)
	pass
	# call editor with file and line number
	elif not unsafe:
	_, d2, _ = compute_new_doc(
	docstring,
	filename,
	level=nindent,
	compact=compact,
	meta=meta,
	func_name=func_name,
	config=config,
	)

Not sure if this is possible, but it might be better to return the missing / extra args, combine the data for both calls and have a extra function which prints the report.

Also, if instead of passing func_name we use qname, it correctly reports the function name as A.__init__ (instead of just __init__).