References in function headers

[hagenw]

For most of the functions we added the references directly after the header of the function, see this example:

...
%
%   See also: driving_function_mono_wfs, driving_function_imp_wfs_ps

%   References:
%       D. Opperschall (2002) - "Realisierung eines Demonstrators für
...

This implies that the references are not visible if you use help function_name.

For others some references are mentioned directly in the description text of the header function and are therefore included in the header as well, see the new sphbesselh_zeros implementation (as currently discussed in #152):

...
%
%   See also: sphbesselh, driving_function_imp_nfchoa
%
%   References:
%
%       N. Hahn, S. Spors (2017) - "Further Investigations on the Design of
...

@fietew, @narahahn, @fs446, @trettberg, @VeraE, @chris-hld Should we stick to this behavior? So, every time references are mentioned in the description include them in the function header and if they are not mentioned exclude them. This has the advantage that the help text in Matlab is less cluttered. Or are you in favor to include them all of the time? This would have the advantage that its easier for a user to find directly related literature.

[fs446]

Matlab seems to consistently utilize the first convention.

This would have the advantage that its easier for a user to find directly related literature. For sure, although I guess that really interested users have a look into the function’s code anyway.

I’d go for the first convention.

On 07 Jul 2017, at 10:07 AM, Hagen Wierstorf notifications@github.com wrote:

For most of the functions we added the references directly after the header of the function, see this example:

...

% % See also: driving_function_mono_wfs, driving_function_imp_wfs_ps

% References: % D. Opperschall (2002) - "Realisierung eines Demonstrators für

...

This implies that the references are not visible if you use help function_name.

For others some references are mentioned directly in the description text of the header function and are therefore included in the header as well, see the new sphbesselh_zeros implementation (as currently discussed in #152):

...

% % See also: sphbesselh, driving_function_imp_nfchoa % % References: % % N. Hahn, S. Spors (2017) - "Further Investigations on the Design of

...

@fietew, @narahahn, @fs446, @trettberg, @VeraE, @chris-hld Should we stick to this behavior? So, every time references are mentioned in the description include them in the function header and if they are not mentioned exclude them. This has the advantage that the help text in Matlab is less cluttered. Or are you in favor to include them all of the time? This would have the advantage that its easier for a user to find directly related literature.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[fietew]

I would like get a much information as possible with the console command help <function_name>. So I would prefer the option, where the references are displayed in the returned text.

[hagenw]

OK, the opinions on this are mixed like our current handling of it in the Toolbox. I think I'm also a little bit in favor of having the references as part of the help message, in the best case also including a url (e.g. doi) link. For normal Matlab stuff I also like when the help message is not cluttered by references, but for our Toolbox I guess the possible user basis is really focused on research in sound field synthesis and it is very likely that they are interested in getting the references easily.

As I'm still open for both solutions are there other opinions on this topic? /cc @narahahn @trettberg @VeraE @chris-hld

[VeraE]

I'd go for the version 2 with displayed references as well.

[hagenw]

I implemented now the second version.