Improve docstrings for norm, vecnorm, normalize and normalize! #21611

nalimilan · 2017-04-28T12:48:33Z

Add equations defining the norms, reorganize the docstrings by argument type,
and mention what "normalizing" means.

Somebody should really review the equations, as I'm not familiar with matrix norms.

nalimilan · 2017-04-28T12:50:14Z

doc/src/stdlib/linalg.md

@@ -73,6 +73,10 @@ Base.LinAlg.diagm
 Base.LinAlg.scale!
 Base.LinAlg.rank
 Base.LinAlg.norm
+Base.LinAlg.norm(::AbstractVector, ::Real)


Without these, the docstrings for specific methods do not appear at all in the manual, but with these the methods appear each in a separate box, contrary to what happens e.g. for vecnorm. I'm probably missing something. @MichaelHatherly

I hope Michael comes back, we miss you!

In the meantime if he's still traveling, maybe @mortenpi can give input on Documenter issues

As far as I can tell, it's the function norm end line to blame here -- then with Base.LinAlg.norm, Documenter only grabs the docstring attached to that particular declaration. Same behaviour in a simple example. I'm guessing because it's in this case an exact match.. but I am not at all familiar with the docsystem code (neither in Base nor in Documenter).

Not sure whether this should be considered to be a bug or not though. Without this there's no way to exactly match the function foo end docstring I believe, but on the other hand it conflicts with the "grab all docstrings" semantics.

Yeah, it would make sense to include all methods, and not only the function. I can't imagine a situation where you would like to include the docstring for the function, but not for the methods.

tkelman · 2017-04-28T12:57:12Z

base/linalg/generic.jl

+```
+with ``a_{ij}`` the entries of ``A``, and ``m`` and ``n`` its dimensions.
+
+When `p=2`, the matrix norm is the spectral norm, equal to largest singular value of `A`.


equal to the largest

Sacha0 · 2017-04-28T15:24:10Z

base/linalg/generic.jl

-    norm(A, [p::Real=2])
+    norm(A::AbstractArray, p::Real=2)
+
+Compute the `p`-norm of a vector or the operator norm of a matrix `A`,


Perhaps more precisely "the corresponding induced operator norm"?

On second thought "induced operator norm" is redundant, so kindly ignore this comment. Either "corresponding induced norm" or "corresponding operator norm" seems best per your point below :).

Sacha0 · 2017-04-28T15:25:06Z

base/linalg/generic.jl


-Compute the `p`-norm of a vector or the operator norm of a matrix `A`, defaulting to the `p=2`-norm.
+For vectors, this is equivalent to [`vecnorm`](@ref) and  equal to:


Extra space between "and" and "equal"?

Missed this one? :)

Sacha0 · 2017-04-28T15:27:39Z

base/linalg/generic.jl

+norm(x::AbstractVector, p::Real=2) = vecnorm(x, p)
+
+"""
+    norm(A::AbstractMatrix, p::Real=2)

 For matrices, the matrix norm induced by the vector `p`-norm is used, where valid values of


Here the (more confined) term "matrix norm" appears rather than the (more general) "operator norm", whereas the opposite above. Perhaps use "matrix norm" or "operator norm" consistently? I suppose "matrix norm" is more precise where these methods are concerned.

As I said I'm not familiar with this, but reading the Wikipedia page I wouldn't think "matrix norm" is more precise than "operator norm", since there are several definitions for matrix norms.

You're absolutely correct! I had only induced matrix norms in mind. Either induced norm or operator norm seems more precise than matrix norm for these methods. Thanks for setting me right! :)

Sacha0 · 2017-04-28T15:29:54Z

base/linalg/generic.jl


-Normalize the vector `v` in-place with respect to the `p`-norm.
-See also [`vecnorm`](@ref) and [`normalize`](@ref).
+Normalize the vector `v` in-place so that its `p`-norm is equal to unity,


Perhaps simplify "is equal to unity" to "equals unity"? (Edit: Also could nix "the vector" as redundant with the immediately preceding signature?)

Sacha0 · 2017-04-28T15:31:23Z

base/linalg/generic.jl


-Normalize the vector `v` with respect to the `p`-norm.
+Normalize the vector `v` so that its `p`-norm is equal to unity,


Likewise here, perhaps simplify "is equal to unity" to "equals unity"? And could nix "the vector" given redundancy with the immediately preceding signature?

Actually I'd rather keep "the vector", it's not that long and it's a useful information if you jump directly to the description without looking precisely at the signature.

Though I would be happy either way, the documentation on documentation (specifically the third numbered convention) advises against repeating information shown in the method signature (and particularly type information) in the method description proper. Best!

tkelman · 2017-04-29T11:04:10Z

base/linalg/generic.jl

+When `p=2`, the matrix norm is the spectral norm, equal to the largest
+singular value of `A`.
+
+When `p=Inf`, the matrix norm is the the maximum absolute row sum of `A`:


duplicate "the"

tkelman · 2017-04-29T11:06:11Z

base/linalg/generic.jl


-Takes the q-norm of a `RowVector`, which is equivalent to the p-norm with
+For row vectors, return the ``q``-norm of `A` , which is equivalent to the p-norm with


unnecessary space between A and comma

kshyatt · 2017-05-02T01:06:36Z

@nalimilan do you have time to update this? I'd love to see it go in soon.

Add equations defining the norms, reorganize the docstrings by argument type, and mention what "normalizing" means. [av skip]

nalimilan · 2017-05-02T14:27:08Z

I've just pushed an updated commit. Unfortunately, I'm not sure what to do about the Documenter issue.

nalimilan · 2017-05-06T13:43:07Z

I've added a commit which puts the generic description of norm in the docstring for the first method (the one for AbstractVector) to work around the Documenter issue. This is an improvement over the current situation anyway, and should allow moving forward without waiting for a more general solution.

(There's currently a bug in the way Documenter renders inline equations though, see JuliaDocs/Documenter.jl#479.)

Sacha0

lgtm for the workaround commit! :) (Absent objections, requests for time, or someone beating me to it, I plan to merge this tomorrow morning.)

* Improve docstrings for norm, vecnorm, normalize and normalize! Add equations defining the norms, reorganize the docstrings by argument type, and mention what "normalizing" means. * Remove docstring for the norm() function (cherry picked from commit e257ef4)

nalimilan commented Apr 28, 2017

View reviewed changes

tkelman reviewed Apr 28, 2017

View reviewed changes

Sacha0 reviewed Apr 28, 2017

View reviewed changes

kshyatt added docs This change adds or pertains to documentation linear algebra Linear algebra labels Apr 28, 2017

nalimilan force-pushed the nl/norms branch from 0199060 to b20ccf6 Compare April 28, 2017 16:36

tkelman reviewed Apr 29, 2017

View reviewed changes

nalimilan force-pushed the nl/norms branch from b20ccf6 to fdaa1dc Compare May 2, 2017 14:25

Improve docstrings for norm, vecnorm, normalize and normalize!

28a635c

Add equations defining the norms, reorganize the docstrings by argument type, and mention what "normalizing" means. [av skip]

nalimilan force-pushed the nl/norms branch from fdaa1dc to 28a635c Compare May 2, 2017 14:26

tkelman added the backport pending 0.6 label May 4, 2017

Remove docstring for the norm() function

72b3643

Sacha0 approved these changes May 6, 2017

View reviewed changes

Sacha0 merged commit e257ef4 into master May 7, 2017

tkelman deleted the nl/norms branch May 7, 2017 19:54

tkelman removed the backport pending 0.6 label May 18, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve docstrings for norm, vecnorm, normalize and normalize! #21611

Improve docstrings for norm, vecnorm, normalize and normalize! #21611

nalimilan commented Apr 28, 2017

nalimilan Apr 28, 2017

tkelman Apr 29, 2017

mortenpi May 3, 2017

nalimilan May 3, 2017

tkelman Apr 28, 2017

Sacha0 Apr 28, 2017

Sacha0 Apr 28, 2017 •

edited

Loading

Sacha0 Apr 28, 2017

Sacha0 Apr 29, 2017

Sacha0 Apr 28, 2017

nalimilan Apr 28, 2017

Sacha0 Apr 28, 2017

Sacha0 Apr 28, 2017 •

edited

Loading

Sacha0 Apr 28, 2017

nalimilan Apr 28, 2017

Sacha0 Apr 29, 2017

tkelman Apr 29, 2017

tkelman Apr 29, 2017

kshyatt commented May 2, 2017

nalimilan commented May 2, 2017

nalimilan commented May 6, 2017

Sacha0 left a comment


		Compute the `p`-norm of a vector or the operator norm of a matrix `A`, defaulting to the `p=2`-norm.
		For vectors, this is equivalent to [`vecnorm`](@ref) and equal to:


		Normalize the vector `v` with respect to the `p`-norm.
		Normalize the vector `v` so that its `p`-norm is equal to unity,


		Takes the q-norm of a `RowVector`, which is equivalent to the p-norm with
		For row vectors, return the ``q``-norm of `A` , which is equivalent to the p-norm with

Improve docstrings for norm, vecnorm, normalize and normalize! #21611

Improve docstrings for norm, vecnorm, normalize and normalize! #21611

Conversation

nalimilan commented Apr 28, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sacha0 Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sacha0 Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kshyatt commented May 2, 2017

nalimilan commented May 2, 2017

nalimilan commented May 6, 2017

Sacha0 left a comment

Choose a reason for hiding this comment

Sacha0 Apr 28, 2017 •

edited

Loading

Sacha0 Apr 28, 2017 •

edited

Loading