RFC: Add documentation for givens, ldltfact!, and eigvals!. Fixes #10526

[andreasnoack]

I think this shouldn't be merged before the other doc changes are completed.

Please check for bad language, typos and errors.

[kshyatt]

i2<=Size(A,1) should be size, right?

[mschauer]

Same above.

[kshyatt]

Now that #12835 is merged, is this ready to go?

[yuyichao]

If these are public doc, they should follow the format of other doc in helpdb.jl and add the function signature to the relavant section in the rst doc

[andreasnoack]

@yuyichao Is this process described anywhere? I don't really understand the new system. Would you explain "..add the function signature to the relavant section in the rst doc"?

[KristofferC]

The documentation strings should look like this, where the method signature is intented as the line in the doc string:

doc"""
    chol(A, [LU]) -> F

Compute the Cholesky factorization of a symmetric positive definite matrix `A`
and return the matrix `F`. If `LU` is `Val{:U}` (Upper), `F` is of type `UpperTriangular`
and `A = F'*F`. If `LU` is `Val{:L}` (Lower), `F` is of type `LowerTriangular` and 
`A = F*F'`. `LU` defaults to `Val{:U}`.
"""

In the .rst file where the doc should go there should be a corresponding entry, like:

.. function:: chol(A, [LU]) -> F

The documentation will then automatically be inserted in the .rst-file when genstdlib.jl is run.

[andreasnoack]

@KristofferC Thanks. We better write that down somewhere at some point.

[yuyichao]

I thought @jakebolewski put it in CONTRIBUTE.md but I guess it doesn't include the part about adding new function docs. Since I don't see that the genstdlib hack is going away anytime soon, I agree it's probably better to add this too...

[JeffBezanson]

This is one of 2 remaining 0.4 issues. Is this release blocking? Please merge or remove the milestone as soon as practical.

[andreasnoack]

Okay. I think this one is ready for review now. To counter comments on the lack of hard newlines: I still think new lines should be soft because

1. it allows users to have the terminal width that suits them without getting an ugly combination hard and soft new lines
2. you can edit the text without adjust all lines in a paragraph.
3. markup features result in a different line lenght in source and rendered text anyway

If there is now a consensus for hard newlines and if the parsing of newlines works then I'll of course update the pr.

[KristofferC]

A new line in the doc string doesn't count as a hard newline does it? I thought markdown didn't care about single new lines. Does the in-terminal-help hard break the line on single new lines in doc strings?

[tkelman]

Github refuses to wrap long lines in julia code. Until that changes we should wrap long lines for review and readability.

[andreasnoack]

@KristofferC you are right. So it is only a matter of formatting the source.

@tkelman I don't wan't this pr to take much longer so I've hit enter a couple of times in the source. However, I've just realized that GitHub's split mode actually wraps lines so if you switch to that you'll probably see a nice altenation between soft and hard newlines where every second line has one word.