Skip to content

Commit

Permalink
Add informative comment.
Browse files Browse the repository at this point in the history
  • Loading branch information
Ismael-VC committed Jun 22, 2015
1 parent efe9a17 commit f1b7b62
Showing 1 changed file with 1 addition and 0 deletions.
1 change: 1 addition & 0 deletions test/sorting.jl
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ end
@test searchsorted([1,2,3], 0) == 1:0
@test searchsorted([1,2,3], 4) == 4:3

# exercise the codepath in searchsorted* methods for ranges that check for zero step range

This comment has been minimized.

Copy link
@Ismael-VC

Ismael-VC Jun 23, 2015

Author Contributor

This makes me wonder. When are we recommended to start using @doc syntax? MichaelHatherly/Docile.jl#141

@doc """
# `ConstantRange`

Exercise the codepath in `searchsorted*` methods for
ranges that check for **zero** step range.
""" ->
immutable ConstantRange{T} <: Range{T}
   val::T
   len::Int
end

This comment has been minimized.

Copy link
@ivarne

ivarne Jun 23, 2015

Member

In test/, I think we should at least wait until the syntax has been used for documentation of Base for å while.

I don't think the interactive features that @doc provides (will provide) is especially attractive for a dummy range type in a test anyway . In my mind @doc is for documentation of APIs and should be meaningful without reading the code. Comments is for explaining the implementation when it isn't obvious what the intention of some code is.

This comment has been minimized.

Copy link
@Ismael-VC

Ismael-VC Jun 23, 2015

Author Contributor

I agree with you in that docstrings are for APIs, and comments are for implementation details. But what I'm really wondering is if it is ok to start sending you guys PR, to add docstrings to undocumented code or code that already have comments that should be docstirngs instead of comments? And perhaps also add some comments here and there where missing.

wait until the syntax has been used for documentation of Base for å while.

I can help hasten that!

This comment has been minimized.

Copy link
@Ismael-VC

Ismael-VC Jun 23, 2015

Author Contributor

I understand that you will be extremely busy with Arraymageddon and complicated stuff like that and I can't help you with those yet, so I can at least help with documentation (in all aspects) and testing instead.

But I wanted to know if it's ok to start doing this beforehand, else I can keep helping with whatever else is more useful/needed.

This comment has been minimized.

Copy link
@StefanKarpinski

StefanKarpinski Jun 23, 2015

Member

I agree that docstrings aren't really going to be a first class feature until they're used in Base Julia. And I would very much like to have built-in language support for them – i.e. strings in top-level void context would be parsed as doc strings. I've said several times, however, and I know that @JeffBezanson agrees, that we will not be doing markdown parsing while parsing Julia code – having a markdown parser as a dependency of the Julia parser is simply a non-starter – it is never going to happen. However, @one-more-minute seems disinclined to change the way docstrings work so that markdown parsing can happen at render time instead of at parse time. Given that, we seem to be at an impasse. Thus, docstrings are stuck in limbo as a clever macro hack rather than a first class language feature.

This comment has been minimized.

Copy link
@MikeInnes

MikeInnes Jun 23, 2015

Member

I don't think that's entirely fair – the last thing I want is to hold things back, and I'm actually working on making the various parts lazier right now so that we can do a full transition.

The main reason I haven't had lazy markdown parsing high on the priority list is that I didn't realise it was blocking anything. If the parser simply treats "foo" as @doc doc"foo" ->, the only hard dependency is the @doc macro (though at expansion time, not parse time), and thanks to the bootstrapping code @doc doesn't even depend on the doc system, let alone the markdown parser – making changes to @doc (e.g. adding laziness) shouldn't affect parsing at all.

So lazy markdown and/or taking Markdown.jl out of Base is fine, but it seems orthogonal to the parser changes, and if it's not likely to cause problems later on I'm not sure why we'd prioritise it over other issues. (Unless there's something I'm missing?)

This comment has been minimized.

Copy link
@StefanKarpinski

StefanKarpinski Jun 23, 2015

Member

Sorry, @one-more-minute, I'm not trying to pick on you – just to push this forward since I really want docstrings in the language. Let's continue discussion over here: #8965.

immutable ConstantRange{T} <: Range{T}
val::T
len::Int
Expand Down

6 comments on commit f1b7b62

@ScottPJones
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 to what @one-more-minute said. I haven't seen him disinclined at all, I imagine, like all of us, he's rather busy, and he has already done some very nice improvements to Docile.jl that just need to be factored correctly into (and out of) Base.

@ScottPJones
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@one-more-minute What about documenting type/immutable members, like Doxygen does?
I find that incredibly useful, it would be nice if a void string (or a ## say) after a member could be added to the documentation (with the info on type name, member name, type, file name/line number).
[this isn't about Doxygen at all, just about saving the metadata for later processing]

@StefanKarpinski
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be a nice-to-have, but the first order of business is getting top-level docstrings into the language.

@ScottPJones
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, yes, fully agree!

@MichaelHatherly
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ScottPJones, different Mike :)

documenting type/immutable members

I've thought about adding that to Docile, shouldn't be too much trouble if I have some time soon.

@ScottPJones
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So it's two Mikes doing all this neat stuff with documentation? OK, I'll try not to get confused again! 😀

Please sign in to comment.