Docstrings

[baggepinnen]

A docstring like this "Plot power spectral density of the signal." Can actually cause more harm than good. Without it, a call to hepl on the function name gives you the signature. With the docstring, you only get the docstring. Compare:

• Without docstring

  No documentation found.
  
  psd2 is a Function.
  
  # 1 method for generic function "psd2":
  [1] psd2(s; fs, nfft, plot, window, legend, kwargs...) in Main at none:2

• With docstring

  help?> psd
  search: psd PosDefException isposdef isposdef! @elapsed pushdisplay @belapsed ls_windowpsd
  
  Plot power spectral density of the signal.

  A nice solution is https://github.com/JuliaDocs/DocStringExtensions.jl that allows you to include $SIGNATURES in the docstring and automatically have it insert all the signatures. An alternative is https://github.com/baggepinnen/AutomaticDocstrings.jl if you want to document all arguments manually.

[mchitre]

Noted. Documentation in this repo is still work in progress, and not in a form that I'd like it to be. Thanks for the pointers, they'll be useful when I'm ready to get the documentation in place.

[mchitre]

Fixed.