remove unnecessary doc string macros, re-sync documentation #14310
Conversation
jakebolewski
added
linear algebra
| @@ -149,7 +149,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f | |||
|
|
|||
| .. Docstring generated from Julia source | |||
|
|
|||
| Compute an ``LDLt`` factorization of a real symmetric tridiagonal matrix such that ``A = L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector. The main use of an ``LDLt`` factorization ``F = ldltfact(A)`` is to solve the linear system of equations ``Ax = b`` with ``F\b``\ . | |||
| Compute an ``LDLt`` factorization of a real symmetric tridiagonal matrix such that ``A = L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector. The main use of an ``LDLt`` factorization ``F = ldltfact(A)`` is to solve the linear system of equations ``Ax = b`` with ``F``\ . | |||
There was a problem hiding this comment.
is this a mistake in escaping, or a bug?
|
|
|
I would have assumed that the two are synonymous, but now we have two different ways to do the same thing with subtle differences that are not documented. We really should just have one syntax for this stuff that everyone uses. |
|
@jakebolewski is right. I'm almost inclined to require |
|
I'd support requiring the |
|
I'm fine with special-casing |
|
I think the ship has sailed on requiring the |
As opposed to subtly breaking all code that uses arrays? |
|
How is this breaking all code that uses arrays? |
|
Getting a good documentation system that just works is one of the most important things to get right. I'm just advocating that on the whole if we have to make something backwards incompatible to fix corner cases then we should, given the magnitude of other proposed changes for 0.5. |
|
No one is arguing that we should have a broken documentation system. I think we should get rid of all of the |
|
Having only the bare string version is also fine with me. |
|
Arraymageddon with views as default? |
|
How is Arraymageddon relevant to this issue? |
|
That "ship has sailed" pronouncements are not necessarily accurate for things like this. There were some comments on the FRBNY announcement post from people who had never seen Julia that raw docstrings make it difficult to distinguish code from non-code. I'd be +1 on always needing |
Syntax highlighting? |
|
Sure but sometimes you have to read code in monochrome. Changing the latex syntax would probably be good anyway, since there could be interpolation cases where you'd want normal string rules to apply. For example auto inserting the signature which we don't have a way of doing yet. |
|
I agree that syntax highlighting is a good approach to addressing this – especially since we'll want to syntax highlight the markdown as markdown. There was also a complaint about multiline comments, which I'm much more sympathetic to since it's at the top of my regrettable features list. |
|
Having Julia code be illegible in editors that have not been configured to highlight julia isn't great. Syntax highlighting is a convenience, it shouldn't be mandatory to understand things. |
|
But I don't see how |
|
Yeah, I don't see what the issue is – strings get highlighted as strings if you don't have support for highlighting them as code. Guiding language designed based on the most broken possible editor configuration doesn't seem like it goes anywhere good. |
|
The comments @tkelman is referring to in case people want to judge the apt level of concern: https://news.ycombinator.com/item?id=10671581 I see the issue and I think it's a problem for basically any form of extensive inline documentation. |
|
I'm going to close this since I think #14378 makes it redundant. |
No description provided.