On Thursday, 17 December 2015 at 07:19:04 UTC, Jon D wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
Many useful ideas in this thread. One I don't recall seeing - a
On 12/17/2015 01:06 AM, John Colvin wrote:
One doesn't need to know any results or definitions from complexity
theory in order to understand what O(n) means. What it means here is
that for large enough n the actual number is bounded from above by n
multiplied by some unspecified constant.
(In
On Wednesday, 16 December 2015 at 23:02:53 UTC, H. S. Teoh wrote:
Any programmer that has any pretense of caring about the
performance of their code ought to know what O(n) means. It's
not that hard to understand. There are plenty of online
resources to learn about this, even if you didn't
On Monday, 14 December 2015 at 20:16:25 UTC, H. S. Teoh wrote:
Imagine, for example, if the docs were to be formatted a little
better, say something like this:
bool isSameLength(Range1, Range2)
(Range1 r1, Range2 r2)
if (isInputRange!Range1 &&
On Wednesday, 16 December 2015 at 18:25:31 UTC, Luís Marques
wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
Just today:
- "Where's the documentation for makeIndex?"
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
Just today:
- "Where's the documentation for makeIndex?"
- http://imgur.com/4SQckvN
- "AHH!" *runs away*
On Thu, Dec 17, 2015 at 12:00:03AM +0100, Timon Gehr via Digitalmars-d wrote:
> On 12/15/2015 12:26 PM, rumbu wrote:
> >
> >And personally, I found the MS remark more compact and more user
> >friendly than:
> >
> >"This is a best-effort implementation of length for any kind of
> >range. If
On 12/15/2015 12:26 PM, rumbu wrote:
And personally, I found the MS remark more compact and more user
friendly than:
"This is a best-effort implementation of length for any kind of range.
If hasLength!Range, simply returns range.length without checking upTo
(when specified). Otherwise, walks
On Wednesday, 16 December 2015 at 18:25:31 UTC, Luís Marques
wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
Just today:
- "Where's the documentation for makeIndex?"
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
Many useful ideas in this thread. One I don't recall seeing - a
standard way to denote whether a routine is lazy or eager. I'm
On Thursday, 17 December 2015 at 00:06:05 UTC, John Colvin wrote:
Given a running time R(n), the time-complexity is given by
O(f(n)) iff df/dn = lim_{n -> inf} dR(n)/dn
Is that also a correct expression? Obviously I'm papering over
the discretisation, but well, I did say physicist... :)
On Wednesday, 16 December 2015 at 23:00:03 UTC, Timon Gehr wrote:
On 12/15/2015 12:26 PM, rumbu wrote:
And personally, I found the MS remark more compact and more
user
friendly than:
"This is a best-effort implementation of length for any kind
of range.
If hasLength!Range, simply returns
On Tue, 15 Dec 2015 15:55:31 +, ZombineDev wrote:
> On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
>>
>> We are talking about a better documentation, not about the C# vs D
>> performance, we already know the winner. Since C# is an OOP-only
>> language, there is only one way to do
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
Something has to be done with the
On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
On Tuesday, 15 December 2015 at 02:39:16 UTC, Steven
Schveighoffer wrote:
[...]
I started exploring D a couple of months ago and I was the
original poster in the reddit thread who sparked this
discussion. While on the topic of
On Tue, 15 Dec 2015 16:10:49 +, wobbles wrote:
> I think some whitespace and some color-coding will go a long way to
> making the function signatures better.
We'll want to make sure we test with color-blindness filters, of course.
On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
We are talking about a better documentation, not about the C#
vs D performance, we already know the winner. Since C# is an
OOP-only language, there is only one way to do reflection -
using OOP, (voluntarily ignoring the fact that
On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
I started exploring D a couple of months ago and I was the
original poster in the reddit thread who sparked this
discussion. While on the topic of documentation I wanted to
quickly put in my thoughts about what frustrated me with
On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
- Runnable examples would be *so* useful! They're present on
the homepage, why can't the examples provided in the inline
docs be runnable as well?
[snip]
Here's an imgur album I created to show some suggestions for
function
On 12/15/2015 11:24 AM, landaire wrote:
On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
I started exploring D a couple of months ago and I was the original
poster in the reddit thread who sparked this discussion. While on the
topic of documentation I wanted to quickly put in my
On Tue, 15 Dec 2015 09:09:43 +, Adrian Matoga wrote:
> Fantastic example of why this strategy should be just banned.
Just as well I wasn't recommending it as a long-term solution. I was more
offering it as additional evidence that template definitions can get a
bit large and people have
On Tuesday, 15 December 2015 at 14:41:34 UTC, Adam D. Ruppe wrote:
Just something I want to throw out as a reminder, a part of the
ranges chapter of my book is public on the packt website:
https://www.packtpub.com/books/content/ranges
and a longer things from Mike Parker's book is too:
On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
Here's an imgur album I created to show some suggestions for
function signatures: http://imgur.com/a/njHKI
I really like the one titled "Put more emphasis on the function
signature". With proper spacing and reducing the noise
On 12/15/2015 03:08 AM, landaire wrote:
- Runnable examples would be *so* useful! They're present on the
homepage, why can't the examples provided in the inline docs be runnable
as well?
The runnable examples were first provided by nazriel (he's to be found
around here and on IRC). He also
On Tuesday, 15 December 2015 at 02:39:16 UTC, Steven
Schveighoffer wrote:
On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
InputRange find(alias pred = "a == b", InputRange,
Element)(InputRange
haystack, Element needle) if (isInputRange!InputRange &&
is(typeof(binaryFun!pred(haystack.front,
On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
...
Take for example C# Docs:
On 2015-12-15 04:51, Jakob Ovrum wrote:
One possible trick is to use multiple `Params:` sections. Optional
parameters can be described as such in the parameter description to
reduce the number of `Params:` sections needed.
Yardoc, used in the Ruby world, allows to do something similar. It has
On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright wrote:
This reminds me of the Tango strategy for this kind of thing.
tango.core.Array was arranged like this:
version(TangoDoc) {
/** Documentation comment. */
bool isSameLangth(Range1, Range2)(Range1 r1, Range2 r2) {
return
On Tuesday, 15 December 2015 at 09:57:00 UTC, ZombineDev wrote:
And then you have one of the most used methods - .Count:
https://msdn.microsoft.com/en-us/library/bb338038(v=vs.100).aspx
Where presumably, for the sake of simplicity, the docs don't
even bother to mention that it is almost
On Tuesday, 15 December 2015 at 09:57:00 UTC, ZombineDev wrote:
And then you have one of the most used methods - .Count:
https://msdn.microsoft.com/en-us/library/bb338038(v=vs.100).aspx
Where presumably, for the sake of simplicity, the docs don't
even bother to mention that it is almost
On Tuesday, 15 December 2015 at 16:12:18 UTC, Chris Wright wrote:
On Tue, 15 Dec 2015 09:09:43 +, Adrian Matoga wrote:
Fantastic example of why this strategy should be just banned.
Just as well I wasn't recommending it as a long-term solution.
I was more offering it as additional
On Tuesday, 15 December 2015 at 19:51:37 UTC, Andrei Alexandrescu
wrote:
I suggest you start with the simpler stuff, such as better
formatting of overloads. That'll allow you to find your way
around the doc build and see what the macros are and what they
generate. It'd be great if you got the
On 12/15/2015 09:40 AM, John Colvin wrote:
On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
This is a *good* documentation:
- "Count" is a better name than "walkLength"; every other programming
language will use concepts similar to count, cnt, length, len.
meh, I like walkLength.
On Tuesday, 15 December 2015 at 11:26:04 UTC, rumbu wrote:
Looking at the .net source code, the Count extension method is
also doing a best effort "count" by querying the ICollection
interface.
Yes, I have looked at the source code, before writing this, so I
knew exactly how it worked. In
On Tuesday, 15 December 2015 at 12:28:02 UTC, ZombineDev wrote:
Not everybody is licensed in computational complexity theory
to understand what O(n) means.
LOL. Personally, I would never want to use any software written
by a programmer, who can't tell the difference.
Well ok, let's consider
On 12/14/15 10:51 PM, Jakob Ovrum wrote:
On Tuesday, 15 December 2015 at 03:47:30 UTC, Andrei Alexandrescu wrote:
We use this pattern in only a couple of places in Phobos, but I think
we should generally improve the language to use less, not more, of it.
BTW I think all overloads of a given
On Tuesday, 15 December 2015 at 13:47:20 UTC, Ola Fosheim Grøstad
wrote:
On Tuesday, 15 December 2015 at 12:28:02 UTC, ZombineDev wrote:
Not everybody is licensed in computational complexity theory
to understand what O(n) means.
LOL. Personally, I would never want to use any software
written
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
Something has to be done with the documentation for Phobos
functions that involve ranges and templates. The example I gave
there is
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
(isInputRange!Range1 &&
Just something I want to throw out as a reminder, a part of the
ranges chapter of my book is public on the packt website:
https://www.packtpub.com/books/content/ranges
and a longer things from Mike Parker's book is too:
https://www.packtpub.com/books/content/understanding-ranges
a lot of us
On 12/15/15 9:03 AM, rumbu wrote:
On Tuesday, 15 December 2015 at 12:28:02 UTC, ZombineDev wrote:
On Tuesday, 15 December 2015 at 11:26:04 UTC, rumbu wrote:
Looking at the .net source code, the Count extension method is also
doing a best effort "count" by querying the ICollection interface.
On Tuesday, 15 December 2015 at 09:57:00 UTC, ZombineDev wrote:
On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in
this Reddit thread:
...
Take for example C#
On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
This is a *good* documentation:
- "Count" is a better name than "walkLength"; every other
programming language will use concepts similar to count, cnt,
length, len.
meh, I like walkLength. I hate it when a innocuous looking little
On Tuesday, 15 December 2015 at 12:28:02 UTC, ZombineDev wrote:
On Tuesday, 15 December 2015 at 11:26:04 UTC, rumbu wrote:
Looking at the .net source code, the Count extension method is
also doing a best effort "count" by querying the ICollection
interface.
Yes, I have looked at the source
On Tuesday, 15 December 2015 at 14:08:34 UTC, dnewbie wrote:
But you know I'm newbie...
And that makes your input important. Didn't see your response
before I wrote mine, but we seem to agree. :)
On 15.12.2015 15:03, rumbu wrote:
There is no indication what happens if the range is undefined in D docs.
In fact, inconsistent behavior:
- it will return 0 in case of null arrays;
- it will throw AccessViolation for null ranges (or probably segfault on
Linux);
I don't think the behavior is
On Mon, 14 Dec 2015 18:45:28 -0500, Steven Schveighoffer wrote:
> On 12/14/15 2:04 PM, bachmeier wrote:
>> It's unanimous, at least among the three of us posting in this Reddit
>> thread:
>>
>> https://www.reddit.com/r/programming/comments/3wqt3p/
On Tuesday, 15 December 2015 at 02:34:01 UTC, Steven
Schveighoffer wrote:
Find will handle just about any call you can think of. How can
the docs just say this concisely?
-Steve
I think it's an interesting question to what extent template
constraints are actually suitable at all as human
On Tuesday, 15 December 2015 at 01:50:07 UTC, tcak wrote:
On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright
wrote:
[...]
Hiding conditionals does not seem like to be solution. Here is
my idea:
Show the function:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Then show
On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
InputRange find(alias pred = "a == b", InputRange, Element)(InputRange
haystack, Element needle) if (isInputRange!InputRange &&
is(typeof(binaryFun!pred(haystack.front, needle)) : bool));
InputRange find(alias pred, InputRange)(InputRange
On 12/14/15 2:04 PM, bachmeier wrote:
It's unanimous, at least among the three of us posting in this Reddit
thread:
https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
Something has to be done with the documentation for Phobos
On 12/14/15 8:50 PM, tcak wrote:
Hiding conditionals does not seem like to be solution. Here is my idea:
Show the function:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Then show the conditions separately:
if(
isInputRange!Range1 &&
isInputRange!Range2 &&
!isInfinite!Range1
On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright wrote:
On Mon, 14 Dec 2015 18:45:28 -0500, Steven Schveighoffer wrote:
On 12/14/15 2:04 PM, bachmeier wrote:
It's unanimous, at least among the three of us posting in
this Reddit thread:
On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer
wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
D is doomed if new users have to
On 12/14/15 9:34 PM, Steven Schveighoffer wrote:
On 12/14/15 8:50 PM, tcak wrote:
Hiding conditionals does not seem like to be solution. Here is my idea:
Show the function:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Then show the conditions separately:
if(
isInputRange!Range1
On Tuesday, 15 December 2015 at 03:47:30 UTC, Andrei Alexandrescu
wrote:
We use this pattern in only a couple of places in Phobos, but I
think we should generally improve the language to use less, not
more, of it.
BTW I think all overloads of a given function should be under
the same DDOC
On 12/14/15 8:10 PM, Chris Wright wrote:
version(TangoDoc) {
/** Documentation comment. */
bool isSameLangth(Range1, Range2)(Range1 r1, Range2 r2) {
return true;
}
} else {
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (
isInputRange!Range1 &&
On 12/14/15 4:11 PM, H. S. Teoh via Digitalmars-d wrote:
On Mon, Dec 14, 2015 at 08:53:53PM +, Andrei Alexandrescu via Digitalmars-d
wrote:
One thing we definitely need to do is make the template constraints
rendered better in documentation, and also allow user content in them.
We've
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
...
Take for example C# Docs:
https://msdn.microsoft.com/en-us/library/system.collections.arraylist.addrange.aspx
Syntax C#:
public virtual void
On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
...
Take for example C# Docs:
On Mon, Dec 14, 2015 at 08:08:20PM +, Jack Stouffer via Digitalmars-d wrote:
> On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
[...]
> >On the otherhand, imagine a newbie looking:
> >
> >bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
> >(isInputRange!Range1 &&
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
Something has to be done with the
On Mon, Dec 14, 2015 at 07:04:46PM +, bachmeier via Digitalmars-d wrote:
> It's unanimous, at least among the three of us posting in this Reddit
> thread:
>
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
>
> Something has to be
On Monday, 14 December 2015 at 19:50:47 UTC, H. S. Teoh wrote:
There is nothing I can do about this. Who makes these
decisions? Can we change it to something useful?
What would constitute "useful" to you?
Removing what is there and leaving it blank would be better. At
least new D
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
D is doomed if new users have to understand template constraints
and ranges to use the standard library.
It's unanimous, at least among the three of us posting in this
Reddit thread:
https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
Something has to be done with the documentation for Phobos
functions that involve ranges and templates.
On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
It's unanimous, at least among the three of us posting in this
Reddit thread:
https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
Something has to be done with the
On Mon, 14 Dec 2015 19:38:26 +, Jack Stouffer wrote:
> If you're trying to use Phobos without knowing what template constraints
> and ranges are, you're going to have a bad time.
I completely agree about ranges.
On that note, it would be nice if std.range actually told you what
interface a
On Mon, 14 Dec 2015 20:53:53 +, Andrei Alexandrescu wrote:
> One thing we definitely need to do is make the template constraints
> rendered better in documentation, and also allow user content in them.
> We've discussed this several times but no clear path emerged so far.
> Maybe a strong
On Monday, 14 December 2015 at 20:52:15 UTC, Jack Stouffer wrote:
You don't: array1.length == array2.length. isSameLength is
designed for comparing input ranges but optimizes down to
length checks if either range has a defined length. If you are
dealing with strings or arrays you don't need
On Monday, 14 December 2015 at 20:08:20 UTC, Jack Stouffer wrote:
You're not really comparing apples to apples here
In fact I'm not, but the main focus here was about the simplicity
of the layout used on the C# doc. You can see others examples
there easily including templates and generics
One thing we definitely need to do is make the template
constraints rendered better in documentation, and also allow user
content in them. We've discussed this several times but no clear
path emerged so far. Maybe a strong champion would come forward?
I'm thinking along the lines of:
*
On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer
wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
D is doomed if new users have to
On 12/14/2015 12:53 PM, Andrei Alexandrescu wrote:
> I'm thinking along the lines of:
>
> * Change ddoc to output the constraint separately under a
> DDOC_CONSTRAINT macro.
>
> * Allow ddoc comments inside macros:
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
> if
I think it's really just a design issue--I agree that you can't
ignore information about ranges and constraints altogether. But
the documentation doesn't reflect any hierarchy of the importance
of information. In the example:
bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
On Monday, 14 December 2015 at 20:53:53 UTC, Andrei Alexandrescu
wrote:
One thing we definitely need to do is make the template
constraints rendered better in documentation, and also allow
user content in them. We've discussed this several times but no
clear path emerged so far. Maybe a strong
On Monday, 14 December 2015 at 21:02:10 UTC, Meta wrote:
I'm not particularly familiar with DDOC. Is there some
documentation on creating new macros?
This text is output by the compiler, so it would be a matter of
making the compiler output it with more information.
It used to be called
On Monday, 14 December 2015 at 21:02:05 UTC, Ali Çehreli wrote:
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
> if (isInputRange!Range1 && isInputRange!Range2 &&
!isInfinite!Range1 &&
> !isInfinite!Range2
Can we simplify it even more? Just this much:
You know, I think it is a lot
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
I'm not sure what else to say here.
No, stuff like the following is indefensible. The current
On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer
wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
D is doomed if new users have to
On Mon, Dec 14, 2015 at 08:53:53PM +, Andrei Alexandrescu via Digitalmars-d
wrote:
> One thing we definitely need to do is make the template constraints
> rendered better in documentation, and also allow user content in them.
> We've discussed this several times but no clear path emerged so
On Mon, 14 Dec 2015 20:52:15 +, Jack Stouffer wrote:
> C++ is doomed if you have to understand templates and iterators
> to use the STL
C++ existed long before the STL. But a putative C++ clone that had sorely
lacking documentation about iterators and put them everywhere in its
standard
On Monday, 14 December 2015 at 22:31:33 UTC, bachmeier wrote:
On Monday, 14 December 2015 at 20:52:15 UTC, Jack Stouffer
wrote:
You don't: array1.length == array2.length. isSameLength is
designed for comparing input ranges but optimizes down to
length checks if either range has a defined
On 14.12.2015 23:31, bachmeier wrote:
I don't want to debate this. If it's the official position that Phobos
documentation is written for experienced users of the language, then so
be it. I'll have to tell others to use a practical language.
Relax, Jack Stouffer is not the spokesman for D or
83 matches
Mail list logo
