Re: Worst Phobos documentation evar!
On 1/3/2015 8:21 PM, Manu via Digitalmars-d wrote:
template function(Arg)
{
@uda(Arg) void function() { ... }
}
Ah, interesting. I've never written a template function like that.
Hmmm, is that how code is rewritten when compiling? If so, why doesn't
it just work already?
The stuff outside of the function is not in scope with the function, that's why.
I'm not sure it should be put in the scope.
I'm just saying where I'm at with it. It got stuck on problems I
didn't-know-how/couldn't to resolve.
I need to know my design is sound (ie, works), otherwise committing to
the design is the wrong thing to do.
You don't need forceinline to know if your design is sound.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote: I've yet to locate the cause of this problem, it's an unpleasant task trying to wade through the layers of make macro hacks in posix.mak to figure out what went wrong.) I'm not sympathetic because everyone hated my straightforward (but voluminous) makefiles and changed them to what you see now.
Re: Worst Phobos documentation evar!
On Sun, Jan 04, 2015 at 08:56:28PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote: I've yet to locate the cause of this problem, it's an unpleasant task trying to wade through the layers of make macro hacks in posix.mak to figure out what went wrong.) I'm not sympathetic because everyone hated my straightforward (but voluminous) makefiles and changed them to what you see now. Yet another nail in the long-overdue coffin of make. T -- Winners never quit, quitters never win. But those who never quit AND never win are idiots.
Re: Worst Phobos documentation evar!
On Friday, 2 January 2015 at 23:03:19 UTC, Walter Bright wrote: On 12/31/2014 4:39 PM, Adam D. Ruppe wrote: But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic. ironically needing something like LUCKY - an external search engine - to fix... LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example. by the way, how about a link in the docs to source for methods, types and everything?
Re: Worst Phobos documentation evar!
On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote:
I don't believe in the utility of a customizable float implementation. There
is one, but it is pretty much useless. For example, halffloat cannot be
implemented using it.
Why?
The same reason I don't see a point to a 17 bit integer type.
This:
@uda(Arg) void function(Arg)()
{
}
I need to be able to supply a template arg to a UDA. The runtime cpuid
branching tech depends on it, and thus the whole API design depends on
it.
So, yeah they're all coming back to me now slowly :)
There were a number of things I was blocked on. If I can't prove that
my API approach works, then it needs to completely change.
These things were blocking me from proving the design actually works.
Can this one be addressed?
template function(Arg)
{
@uda(Arg) void function() { ... }
}
Well, it kinda does. Swapping register types is one of the biggest
performance hazards there is.
Use of SIMD opcodes will generate use of xmm regs. As much as I preach
best practise is to commit 100% to SIMD, people will inevitably find
themselves moving float data into SIMD regs. x64 should actually be
the most tolerant of that sort of code, because float data *should*
already be in xmm regs, but I think in our case we're going to see
some pretty ordinary simd benchmarks whenever floats appear. The
register swapping will very probably result in code that is slower
than just issuing sequential float ops.
The best thing to do is make the library work, and then we go about making it
faster.
The thing is,
M: Implement feature X and then I can deliver fantastic library A 2 years later.
W: Ok, but I've got to first implement Y because it's blocking delivery of
fantastic library B today.
M: Implement feature X and then I can deliver fantastic library A tomorrow!
W: Ok, it's at the top of the queue!
Re: Worst Phobos documentation evar!
On 4 January 2015 at 13:48, Walter Bright via Digitalmars-d
digitalmars-d@puremagic.com wrote:
On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote:
This:
@uda(Arg) void function(Arg)()
{
}
I need to be able to supply a template arg to a UDA. The runtime cpuid
branching tech depends on it, and thus the whole API design depends on
it.
So, yeah they're all coming back to me now slowly :)
There were a number of things I was blocked on. If I can't prove that
my API approach works, then it needs to completely change.
These things were blocking me from proving the design actually works.
Can this one be addressed?
template function(Arg)
{
@uda(Arg) void function() { ... }
}
Ah, interesting. I've never written a template function like that.
Hmmm, is that how code is rewritten when compiling? If so, why doesn't
it just work already?
Well, it kinda does. Swapping register types is one of the biggest
performance hazards there is.
Use of SIMD opcodes will generate use of xmm regs. As much as I preach
best practise is to commit 100% to SIMD, people will inevitably find
themselves moving float data into SIMD regs. x64 should actually be
the most tolerant of that sort of code, because float data *should*
already be in xmm regs, but I think in our case we're going to see
some pretty ordinary simd benchmarks whenever floats appear. The
register swapping will very probably result in code that is slower
than just issuing sequential float ops.
The best thing to do is make the library work, and then we go about making
it faster.
The thing is,
M: Implement feature X and then I can deliver fantastic library A 2 years
later.
W: Ok, but I've got to first implement Y because it's blocking delivery of
fantastic library B today.
M: Implement feature X and then I can deliver fantastic library A tomorrow!
W: Ok, it's at the top of the queue!
Don't get me wrong, I'm not trying to rearrange priorities. The stuff
going on at the moment is super important!
I'm just saying where I'm at with it. It got stuck on problems I
didn't-know-how/couldn't to resolve.
I need to know my design is sound (ie, works), otherwise committing to
the design is the wrong thing to do.
Re: Worst Phobos documentation evar!
Manu via Digitalmars-d wrote in message
news:mailman.4110.1420345278.9932.digitalmar...@puremagic.com...
template function(Arg)
{
@uda(Arg) void function() { ... }
}
Ah, interesting. I've never written a template function like that.
Hmmm, is that how code is rewritten when compiling? If so, why doesn't
it just work already?
I'm pretty sure you were told about this last time you asked about the same
thing.
Yes, this is how the compiler re-writes function templates internally, but
if you have udas:
@uda(Arg) void function(Arg)() { ... }
becomes
@uda(Arg) template function(Arg)
{
void function() { ... }
}
This makes more sense when you remember that
@uda(Arg) void function(Arg)() { ... }
is identical to
@uda(Arg) { void function(Arg)() { ... } }
so it doesn't make a lot of sense to pull the UDA inside the template.
One weird thing is that it doesn't work with postfix udas either:
void function(Arg)() @uda(Arg) { ... }
Would that be appropriate for your code if it worked? If so, it might be
worth opening an enhancement.
Re: Worst Phobos documentation evar!
On 2 January 2015 at 08:26, Walter Bright via Digitalmars-d
digitalmars-d@puremagic.com wrote:
On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote:
Make it work in dmd (with my help, of course) and prove the design. Then
GDC
will come along.
I can't do anything that isn't supported by the GCC backend; that's
the platform for almost all the cross-compilers, which I really care
about.
I also have a suspicion that anybody who uses SIMD seriously will
probably be building with LDC or GCC because of improved codegen
across the board.
Have to start somewhere.
Or, it might rather just be best to drop such ambitious goals for the
API from the first revision :/
Half-float is here:
http://digitalmars.com/sargon/halffloat.html
in the Sargon component library :-)
That's probably not the best place for it ;)
What was the controversy blocking it? I don't remember.
I think the root issue was nobody thought it was useful other than you and
I. There is a reasonable issue about should this really be in the Standard
Library, or an add-on?
I created Sargon as a place to put things I think would be generally useful,
but have been unable to convince others of.
std.simd would ideally depend on it. half8 is a very useful SIMD primitive.
It might be tricky to define a half8 type in std.simd alongside
float4, short8, etc, that feels sufficiently related to the others and
emits hardware opcodes.
It would be trivial to use halffloat as a model for building other custom
floating point types.
Isn't there a competing custom float implementation though?
Should they be unified?
I don't believe in the utility of a customizable float implementation. There
is one, but it is pretty much useless. For example, halffloat cannot be
implemented using it.
Why?
Well could custom float alternatively be implemented by generalising halffloat?
But I agree that it's basically useless. Half float on the other hand
is a standard type that appears in geometry and image data all the
time these days.
That stuff all needs forceinline too to be particularly useful.
I agree, but that does NOT block you from designing and writing the code.
It
only blocks the final polish.
I wrote the code years ago. I was at the point of polish where it got
stuck on those issues... and unittest's, and documentation _
The last 10% of the work is always 90% of the work. Get it done!
It also may be worthwhile to look through std.algorithm and see what can
be
specialized to use simd, such as string searching.
SSE provides some special opcodes for string processing that aren't
really portable, so I don't expect those would be expressed in
std.simd, but they could be used opportunistically in other places.
The main trouble is that they are SSE4.2, which is still sufficiently
new that we can't rely on it's presence on end-user machines. How will
we tell the compiler it is okay to use those opcodes?
GCC/LDC have args to say what SSE level to build for. We need a way to
query the requested SSE level in the code, and we also need that
concept added to DMD.
std.algorithm is portable for the user. It is very accommodating for
specializations, so most definitely it can be specialized for x86 with SIMD.
Some platforms, such as OSX, have a reliable minimum standard. This is why
we, for example, have abandoned 32 bit OSX. For others, a runtime switch
based on CPUID is fine.
I don't think a runtime switch is practical that far down the call-tree.
We need to be able to supply a SIMD level to the compiler, and
ideally, also change it locally with a pragma or an attribute (GCC and
Clang use an attribute).
Runtime SIMD branch selection needs to be positioned as high up the
stack as possible.
So, where it sits is: DMD needs a commandline arg to request an SSE
target level and made available to the code, I need to work out what
to do about GDC, and I need to write the unittest's and docs... which
is probably the biggest block tbh ;)
Otherwise, it still rests in my fork where I left it. Some people have
used it. When it's done I'll extend it to support matrices, and
perhaps some higher-level linear algebra stuff.
The thing is, if you don't do the unittests and docs, you will be throwing
away all the other work you've done. If you do them, there will be a large
incentive to get forceinline working.
I just recalled another problem actually.
This:
@uda(Arg) void function(Arg)()
{
}
I need to be able to supply a template arg to a UDA. The runtime cpuid
branching tech depends on it, and thus the whole API design depends on
it.
So, yeah they're all coming back to me now slowly :)
There were a number of things I was blocked on. If I can't prove that
my API approach works, then it needs to completely change.
These things were blocking me from proving the design actually works.
Can this one be addressed?
Oh yeah, and a massive one that I've discussed with Ethan and I think
he's discussed with
Re: Worst Phobos documentation evar!
On 2 January 2015 at 08:40, Joseph Rushton Wakeling via Digitalmars-d digitalmars-d@puremagic.com wrote: On 01/01/15 15:43, Manu via Digitalmars-d wrote: Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm - x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work. I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point.
Re: Worst Phobos documentation evar!
H. S. Teoh via Digitalmars-d wrote in message news:mailman.3882.1420060673.9932.digitalmar...@puremagic.com... Yeah no kidding. How do I hate make? Let me count the ways: ... Most of these are only problems with large projects, and large makefiles. For smaller projects make is vastly superior to a shell script, and almost always already installed.
Re: Worst Phobos documentation evar!
On 02/01/15 10:59, Manu via Digitalmars-d wrote: Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work. I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point. I mean the fact that std.math functions on floating point are hardcoded to use real for their input and return types.
Re: Worst Phobos documentation evar!
On 12/31/2014 4:39 PM, Adam D. Ruppe wrote: But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic. ironically needing something like LUCKY - an external search engine - to fix... LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example.
Re: Worst Phobos documentation evar!
On 01/01/15 23:48, Iain Buclaw via Digitalmars-d wrote: I've had the exact same talks as you. I would back any incentive to further push it further (I've only really made tidbit changes). Sounds good, maybe the three of us can follow up on this together some time in the not-too-distant future.
Re: Worst Phobos documentation evar!
On 2015-01-01 00:53, Walter Bright wrote: As I said, I grepped the Phobos sources for $(COMMA), and found 2 instances, neither of which were necessary. And how do you plan to find all commas that should actually be $(COMMA)? -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2015-01-01 00:52, Walter Bright wrote: On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote: ah, the following is even better: Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to. The point is to have consistent look and feel, not be able to customize every single thing. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2014-12-31 21:40, Walter Bright wrote: Documentation for code winds up on a web site. I find it very handy that the Ddoc embedded in D code, and the Ddoc used for the rest of the web site, all use the same style sheets, the same macro files, etc. And an ebook and pdf can all be generated from the same. If, hypothetically, Ddoc was removed and replaced with something completely different, that doesn't mean you need to stop using it. You could even continue to ship it with DMD was a separate tool. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2015-01-01 00:51, Rikki Cattermole wrote: I know. And btw currently ddoc cannot output json. I was considering some form of external tool that used e.g. DScanner to grab all the AST/comments and then parse them a little similar to DDoc just without the macros. You can already get the documentation when generating the JSON using the -X flag. That's how Ddox works, if I recall correctly. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 12/31/14 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. Just write $(ARGS lots, of, commas). -- Andrei
Re: Worst Phobos documentation evar!
On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote: Okay, well it's not really useful without a forceinline attribute. std.simd functions need to be pseudo-intrinsics, ie, the cost of a function call will definitely negate the work they perform. Yes, they will (probably) be inlined in release, but debug performance is also important, and I can't have maths code that runs much slower in debug builds because it makes a function call passing structs by value for every single maths opcode in the hottest loops. There were also troubles with GDC; I haven't been able to make it emit the opcode that I want. It reinterprets to emit something else depending on the SSE level argument passed to the compiler. There are attributes to set the 'target' per-function, but that didn't work for some reason, so I need to work out if that can be resolved, otherwise my whole approach (goal of being able to generate multiple SIMD version code paths for runtime selection) won't work (in GCC)... We need to get a quality low-level API out there, that is portable, and fills gaps in the various architectures, then we can focus on high-level wrappers and niceties. Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along. I really want to see your half-float module merged. Where did that go? I recall some people were saying it should be conflated with the custom-float stuff, so half-float was just a specialisation of custom float... Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-) I'm not so sure about that... but maybe? I have been needing a 3.7 (10bit) float too, maybe that fits in there? It would be trivial to use halffloat as a model for building other custom floating point types. That stuff all needs forceinline too to be particularly useful. I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching.
Re: Worst Phobos documentation evar!
On 31/12/14 14:50, Joseph Rushton Wakeling via Digitalmars-d wrote: Second and more importantly, I ran into some tricky cases implementing Params: lists for functions that have multiple overloads with different parameter lists. Slightly more subtle variant of same: if the first, documented code is a struct or class definition, and the /// ditto'd code blocks are factory functions to generate instances of that code, you get the same warnings, and it means that _none_ of the parameters will have type info attached. (Encountered with e.g. randomCover and randomSample.) On the bright side, PR is in :-) https://github.com/D-Programming-Language/phobos/pull/2831
Re: Worst Phobos documentation evar!
On 1 January 2015 at 19:47, Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote: Okay, well it's not really useful without a forceinline attribute. std.simd functions need to be pseudo-intrinsics, ie, the cost of a function call will definitely negate the work they perform. Yes, they will (probably) be inlined in release, but debug performance is also important, and I can't have maths code that runs much slower in debug builds because it makes a function call passing structs by value for every single maths opcode in the hottest loops. There were also troubles with GDC; I haven't been able to make it emit the opcode that I want. It reinterprets to emit something else depending on the SSE level argument passed to the compiler. There are attributes to set the 'target' per-function, but that didn't work for some reason, so I need to work out if that can be resolved, otherwise my whole approach (goal of being able to generate multiple SIMD version code paths for runtime selection) won't work (in GCC)... We need to get a quality low-level API out there, that is portable, and fills gaps in the various architectures, then we can focus on high-level wrappers and niceties. Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along. I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board. I really want to see your half-float module merged. Where did that go? I recall some people were saying it should be conflated with the custom-float stuff, so half-float was just a specialisation of custom float... Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-) That's probably not the best place for it ;) What was the controversy blocking it? I don't remember. I'm not so sure about that... but maybe? I have been needing a 3.7 (10bit) float too, maybe that fits in there? It would be trivial to use halffloat as a model for building other custom floating point types. Isn't there a competing custom float implementation though? Should they be unified? That stuff all needs forceinline too to be particularly useful. I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation _ It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching. SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD. So, where it sits is: DMD needs a commandline arg to request an SSE target level and made available to the code, I need to work out what to do about GDC, and I need to write the unittest's and docs... which is probably the biggest block tbh ;) Otherwise, it still rests in my fork where I left it. Some people have used it. When it's done I'll extend it to support matrices, and perhaps some higher-level linear algebra stuff. Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm - x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;)
Re: Worst Phobos documentation evar!
On 12/31/14 3:51 PM, Rikki Cattermole wrote: On 1/01/2015 4:23 a.m., Jacob Carlborg wrote: On 2014-12-30 06:13, Rikki Cattermole wrote: Hmm I have an idea. I wonder if I can get ddoc to generate json files. You would still need to write the documentation in Ddoc, which is what we're complaining about. I know. And btw currently ddoc cannot output json. Json generation should follow this mold: https://github.com/D-Programming-Language/dlang.org/pull/737 -- Andrei
Re: Worst Phobos documentation evar!
On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote: Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along. I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board. Have to start somewhere. Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-) That's probably not the best place for it ;) What was the controversy blocking it? I don't remember. I think the root issue was nobody thought it was useful other than you and I. There is a reasonable issue about should this really be in the Standard Library, or an add-on? I created Sargon as a place to put things I think would be generally useful, but have been unable to convince others of. It would be trivial to use halffloat as a model for building other custom floating point types. Isn't there a competing custom float implementation though? Should they be unified? I don't believe in the utility of a customizable float implementation. There is one, but it is pretty much useless. For example, halffloat cannot be implemented using it. That stuff all needs forceinline too to be particularly useful. I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation _ The last 10% of the work is always 90% of the work. Get it done! It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching. SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD. std.algorithm is portable for the user. It is very accommodating for specializations, so most definitely it can be specialized for x86 with SIMD. Some platforms, such as OSX, have a reliable minimum standard. This is why we, for example, have abandoned 32 bit OSX. For others, a runtime switch based on CPUID is fine. So, where it sits is: DMD needs a commandline arg to request an SSE target level and made available to the code, I need to work out what to do about GDC, and I need to write the unittest's and docs... which is probably the biggest block tbh ;) Otherwise, it still rests in my fork where I left it. Some people have used it. When it's done I'll extend it to support matrices, and perhaps some higher-level linear algebra stuff. The thing is, if you don't do the unittests and docs, you will be throwing away all the other work you've done. If you do them, there will be a large incentive to get forceinline working. Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm - x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) That shouldn't affect vector code.
Re: Worst Phobos documentation evar!
On 1 January 2015 at 22:40, Joseph Rushton Wakeling via Digitalmars-d digitalmars-d@puremagic.com wrote: On 01/01/15 15:43, Manu via Digitalmars-d wrote: Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm - x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work. I've had the exact same talks as you. I would back any incentive to further push it further (I've only really made tidbit changes).
Re: Worst Phobos documentation evar!
On 01/01/15 15:43, Manu via Digitalmars-d wrote: Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm - x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;) Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work.
Re: Worst Phobos documentation evar!
On 31/12/14 12:25, Walter Bright via Digitalmars-d wrote: What you can contribute that would be very valuable is what we've discussed before - your simd expertise. Your influence is what has shaped the current simd support. I don't know anyone who knows even half of what you do about simd. What you know could make D really fly with vector math. You and I both know that auto vectorization, the approach used by everyone else, is not the key to high performance simd. We have an opportunity here. FWIW Manu, I would be really excited to see what you could put together here. :-)
Re: Worst Phobos documentation evar!
On 31 December 2014 at 16:28, Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: Remember that UDAs and even Win64 are supported because of your influence. That's actually a pretty nice track record! You've also contributed about 6 pull requests, 5 of which have been merged. I made a forceinline proposal at your request, but it sank under the weight of controversy over how to do it. I don't think I was trying to dismiss those things. They were 3-4 years ago and relatively uncontroversial, and already more or less intended or discussed in the past, I managed to give them a priority nudge. I hope they were all useful things; I know the win64 stuff in particular has made D available to a lot of my friends and colleagues to try out at least, and obviously, we were able to use it at Remedy on the back of those features. UDAs comes up as useful tools all over the place. There seems to be nothing left from me that's uncontroversial. Are you saying that if I worked on the stuff that I believe in, it would have a greater chance of being accepted, despite being outright opposed in conversation? We're talking about stimulating contribution, and I have no idea what I could contribute that would be accepted. And also detailing areas of friction I experience (or perceive) when getting involved in the past. The only thing that comes to mind is debugger related stuff, but I know absolutely nothing about it and it seems like a very large time investment to get up to speed on that stuff such that I could make any useful fixes. Both you and Rainer are more-or-less experts on CV8/PDB already. I would certainly like to resurrect forceinline discussion, but I feel like it's of lower priority than other topics that are receiving attention at the moment, so it's probably better not to distract attention from them for the time being. I wasn't excited about the pragma approach myself, I can't see any advantages... but I also wasn't particularly emotional about it, I'll take what I can get on that front. It just seems like that approach would lead to inconvenience, and possibly more edges to me. How can you do anything generic or meta with a pragma? Yay for text mixins! ;) There were others that felt more strongly about that one than me.
Re: Worst Phobos documentation evar!
My question is how we can break this pattern? What steps can the D leadership take to convince folks like you to actually add, even with the simplest things? Speaking as someone new who enjoys dmd (a lot) and considers contributing * It is really hard to understand what is going on by reading the forum and watching github. * The friction in the forum is just amazing. Very entertaining, but not leading to motivation or contributions. For me to be able to contribute in any meaningful way, clearer guidelines are needed. Both concerning the communication style in forums as well as technical directions such as what needs to be build and why. I feel the D leadership needs to set priorities and steer the whole effort in a coherent direction. Uli
Re: Worst Phobos documentation evar!
What you can contribute that would be very valuable is what we've discussed before - your simd expertise. Your influence is what has shaped the current simd support. I don't know anyone who knows even half of what you do about simd. What you know could make D really fly with vector math. You and I both know that auto vectorization, the approach used by everyone else, is not the key to high performance simd. We have an opportunity here.
Re: Worst Phobos documentation evar!
On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
31-Dec-2014 15:17, Jacob Carlborg пишет: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) simple, effective and well-known ? I have to say all of 3 are wrong. make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. +1 Or rather not, if you like make I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ -- Dmitry Olshansky
Re: Worst Phobos documentation evar!
On 12/31/14 9:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.)
Re: Worst Phobos documentation evar!
On 28/12/14 02:00, Walter Bright via Digitalmars-d wrote:
Anyone want to take this on? There's a lot of stuff like this in Phobos. It's
too much for one person to tackle, but if each of us just pick a function here
and there, we can crowdsource and improve things greatly.
Just been having a play with documenting Params/Returns for the free functions
in std.random. A number of issues encountered.
First, it looks like the build system has changed since I last tried building
docs. If I go with 'make html' in my local phobos branch, the various html
files generated are all empty -- with their content seemingly intended to be
filled by javascript which doesn't work. What gives? :-(
Second and more importantly, I ran into some tricky cases implementing Params:
lists for functions that have multiple overloads with different parameter lists.
As things are, it's convenient -- in terms of reading the code -- to have
different functions ordered from simple to complex signatures, with one
documentation block for the first, and everything else sharing the same
documentation using /// ditto. However, this won't work with a Params: list
because ddoc attempts to match listed parameters to those of the immediately
following function signature.
Trivial example:
/**
* Params:
* rng = (optional) random number generator to use;
* if not specified, defaults to $(D rndGen)
*
* Returns:
* Floating-point random variate of type $(D T) drawn from the uniform
* distribution across the half-open interval [0, 1$(RPAREN).
*/
T uniform01(T = double)()
if (isFloatingPoint!T)
{
return uniform01!T(rndGen);
}
/// ditto
T uniform01(T = double, UniformRNG)(ref UniformRNG rng)
if (isFloatingPoint!T isUniformRNG!UniformRNG)
out (result)
{
assert(0 = result);
assert(result 1);
}
body
{
...
}
The above will generate a warning because, of course, the first function
signature doesn't have a parameter 'rng'. Since docs are compiled with -w, I
believe this will result in an error ... ?
In the above case, of course, it's trivial just to swap the order of the
functions, but in general this is not the case, and it's rather irritating to
have to tweak everything so that functions are listed in order of
complex-to-simple signatures rather than simple-to-complex.
It's also not clear to me that one can in general avoid cases where there is a
group of functions, all doing the same thing, where nevertheless there is no
single function signature accepting all the possible parameters; and yet, it's
still very convenient to group together the documentation of those function
signatures.
Re: Worst Phobos documentation evar!
On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. Try for yourself in this online Markdown editor with live preview: http://dillinger.io/ -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 02:50:34PM +0100, Joseph Rushton Wakeling via Digitalmars-d wrote: [...] Second and more importantly, I ran into some tricky cases implementing Params: lists for functions that have multiple overloads with different parameter lists. As things are, it's convenient -- in terms of reading the code -- to have different functions ordered from simple to complex signatures, with one documentation block for the first, and everything else sharing the same documentation using /// ditto. However, this won't work with a Params: list because ddoc attempts to match listed parameters to those of the immediately following function signature. This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 T -- Some ideas are so stupid that only intellectuals could believe them. -- George Orwell
Re: Worst Phobos documentation evar!
On 2014-12-30 00:52, Walter Bright wrote: (And I should ask, what if you wanted a | in the Markdown?) Just type a |. You don't need to escape most Markdown symbols in the middle of text. And like I said, what about all the separators in Markdown? What are you going to do with , `, |, -, #, and all the other special characters? It's not like you'll never need them when documenting code. Most of the time it's not a problem, see above. The only symbols that can cause a problem will most likely be used inside a code block anyway, where they are not interpreted as Markdown. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2014-12-30 04:13, Kiith-Sa wrote: D blocks in DDoc are usually in: --- code here --- With a Markdown-like syntax, inline code could be in `inline code here` . I admit you would need to escape the backticks, which are very rare, especially in inline code fragments. I also admit *that* would force you to not reliably use *some* D code fragments *outside* backticks. And I find it unlikely that there are more than 3 fragments in entire Phobos doc this would break. You only need to escape backticks in inline code, not code blocks, i.e. ``` auto a = `foo` ``` The above works perfectly fine. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2014-12-30 02:38, Andrei Alexandrescu wrote: I'm with Walter here - I find Markdown and its ilk inferior to macro systems. -- Andrei I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing documentation for code. Not web sites, not books, but documentation for code. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. ::barf:: This, too, is not Markdown.
Re: Worst Phobos documentation evar!
On 2014-12-30 06:13, Rikki Cattermole wrote: Hmm I have an idea. I wonder if I can get ddoc to generate json files. You would still need to write the documentation in Ddoc, which is what we're complaining about. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 2014-12-29 23:44, Walter Bright wrote: I know. That's what's wrong with it. It is severely underpowered, and so uses a wretched hybrid approach like C uses a preprocessor because it is underpowered. That's what's making it better than ddoc. 90% of the time that power is not needed. Ddoc is instead making that 90% of the documentation a lot harder to write In reddit, is it [link](description) or [description](link) or (link)[description] or (description)[link]? I have to read the dam help file every time. No, I can't remember what it is for which Markdown flavor, either. If it's uses anything other than [text](url) it's not Markdown, period. BTW, using macros have cut my web page writing time by about 75%. It's also a joy to just change the macro definitions and voila! the whole web site fixes itself. Using Ruby and Haml has improved the time it takes for me to write a web site. I can just change a Ruby function or a template the whole site changes. That doesn't mean I just Ruby and Haml to document my code. Pick the write tool for the job. Markdown is not the right tool to use for writing a book or a complete web site. Ddoc is not the right tool for documenting code. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Re: Worst Phobos documentation evar!
On 12/31/2014 4:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. You can not like a car's suspension but still like its engine.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:03 AM, Ary Borenszweig wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) Which one has a better text macro system?
Re: Worst Phobos documentation evar!
On 12/31/2014 7:03 AM, Jacob Carlborg wrote: On 2014-12-30 00:52, Walter Bright wrote: (And I should ask, what if you wanted a | in the Markdown?) Just type a |. You don't need to escape most Markdown symbols in the middle of text. And when you want a | in a table entry? Most of the time it's not a problem, see above. And when it is, how do you escape them?
Re: Worst Phobos documentation evar!
On 12/31/2014 6:29 AM, Jacob Carlborg wrote: On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things?
Re: Worst Phobos documentation evar!
On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright wrote: On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point. It's NOT a different variant. It's a different LANGUAGE. That's like saying D is a variant of Pascal.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright wrote: On 12/31/2014 7:20 AM, Vladimir Panteleev wrote: On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote: * reddit * github These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines. Yes, the same only different. Just like DDoc macros and Makefile macros. They're the same, but different. Also, the differences between Markdown implementations are trivial, and do not effect the readability of the source, which is the entire point of Markdown - making the plain-text readable, rather than polluting it with HTML (or DDoc) tag noise. * wiki * hackernews Hacker News and both the new D Wiki, and the old, do not use Markdown. It's just another variation of it - which is my point. And your point is completely wrong. DDoc and Makefiles both use $(MACROS), does that mean that DDoc is a variation of Make? Yes, *lots* of things use common elements. Because that makes things more easily understood when *reading*, which is the single most important thing for documentation. The macros are fine for when they are needed, but you shouldn't have to use gotos and jumps when all you want is a gorram foreach loop. Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things? A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping?
Re: Worst Phobos documentation evar!
On 12/31/2014 11:45 AM, Kiith-Sa wrote:
It's NOT a different variant. It's a different LANGUAGE.
That's like saying D is a variant of Pascal.
It's not illegitimate to consider all { } languages as variants of each other.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 20:05:43 UTC, Walter Bright
wrote:
On 12/31/2014 11:45 AM, Kiith-Sa wrote:
It's NOT a different variant. It's a different LANGUAGE.
That's like saying D is a variant of Pascal.
It's not illegitimate to consider all { } languages as variants
of each other.
With that kind of thinking everyone would still be using COBOL
and FORTRAN.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 10:59:32 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 4:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. You can not like a car's suspension but still like its engine. but 'make' is a failure in every aspect, especially GNU make. bwah, build tool that can't do autoimatic dependency tracking? you must be joking. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 11:59 AM, Anon wrote: A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping? Yeah, the reason that people have added WYSIWYG string literals to languages :-)
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 11:14:50 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 6:29 AM, Jacob Carlborg wrote: On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things? that still will be MUCH better than Ddoc. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 7:13 AM, Jacob Carlborg wrote: I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing documentation for code. Not web sites, not books, but documentation for code. Documentation for code winds up on a web site. I find it very handy that the Ddoc embedded in D code, and the Ddoc used for the rest of the web site, all use the same style sheets, the same macro files, etc. And an ebook and pdf can all be generated from the same.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 12:05:30 -0800
Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote:
On 12/31/2014 11:45 AM, Kiith-Sa wrote:
It's NOT a different variant. It's a different LANGUAGE.
That's like saying D is a variant of Pascal.
It's not illegitimate to consider all { } languages as variants of each other.
then D is doomed to vanish. nobody needs another C++, but with broken
syntax and without libraries.
signature.asc
Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/14 4:07 PM, Walter Bright wrote: On 12/31/2014 5:03 AM, Ary Borenszweig wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) Which one has a better text macro system? A real programming language without text macro systems.
Re: Worst Phobos documentation evar!
On 12/31/14 4:14 PM, Walter Bright wrote: On 12/31/2014 6:29 AM, Jacob Carlborg wrote: On 2014-12-30 01:10, Walter Bright wrote: It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup. You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things? You use a backslash character, like in almost every programming language, json, etc. http://daringfireball.net/projects/markdown/syntax#backslash Compare \* to $(STAR)
Re: Worst Phobos documentation evar!
On 12/31/14 5:33 PM, Walter Bright wrote: On 12/31/2014 11:59 AM, Anon wrote: A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping? Yeah, the reason that people have added WYSIWYG string literals to languages :-) Which still look readable (and the backslash is just one character of noise so it's also not that bad).
Re: Worst Phobos documentation evar!
On 12/31/14 4:09 PM, Walter Bright wrote: On 12/31/2014 7:03 AM, Jacob Carlborg wrote: On 2014-12-30 00:52, Walter Bright wrote: (And I should ask, what if you wanted a | in the Markdown?) Just type a |. You don't need to escape most Markdown symbols in the middle of text. And when you want a | in a table entry? Most of the time it's not a problem, see above. And when it is, how do you escape them? Backslash character.
Re: Worst Phobos documentation evar!
On 12/31/2014 11:59 AM, Anon wrote: Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list. You don't have to. You can write it as: $(LIST A, B, C) or: $(LIST A, B, C ) Yes, there currently isn't a LIST macro by default, but you can write one: LISTX=$(LI $1) $(LISTX $+) LIST=$(UL $(LISTX $1, $+)) I very often write custom macros for a particular job at hand. It's very, very handy. For example, suppose I want to switch between a definition list and a table? I write a higher level macro, then switch its definition. I can use the X Macro technique. I can comment out a block. I can create variables. For example, when the D source moved from svn to github, the macro in each source code file that linked to the repository just needed its definition changed. With markdown, I'd have had to have edited every file (what, are there a thousand files?). And so on. http://en.wikipedia.org/wiki/X_Macro
Re: Worst Phobos documentation evar!
On 12/29/14 10:38 PM, Andrei Alexandrescu wrote: On 12/29/14 2:30 PM, Dicebot wrote: DDOC is probably one of D features with pretty idea and hardly usable design. I wish we had something like Markdown instead - can never remember Phobos macros to use and usually just resort to using plain text instead. I'm with Walter here - I find Markdown and its ilk inferior to macro systems. -- Andrei Definitely, because Markdown is not a macro system, it's a documentation tool.
Re: Worst Phobos documentation evar!
On 12/31/2014 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: The above will generate a warning because, of course, the first function signature doesn't have a parameter 'rng'. Since docs are compiled with -w, I believe this will result in an error ... ? I know, I don't care for that warning, which was added fairly recently.
Re: Worst Phobos documentation evar!
On 12/27/14 10:00 PM, Walter Bright wrote: This is so bad there isn't even a direct link to it, it hides in shame. Just go here: http://dlang.org/phobos/std_encoding.html#.transcode and scroll up one entry. Here it is: size_t encode(Tgt, Src, R)(in Src[] s, R range); Encodes c in units of type E and writes the result to the output range R. Returns the number of Es written. Let me enumerate the awesomeness of its awfulness: 1. No 'Return:' block, though it obviously returns a value. 2. No 'Params:' block, though it obviously has parameters. 3. No 'Example:' block 4. No comparison with other 'encode' functions in the same module. 5. No description of what 'Tgt' is. 6. No description of what 'Src' is. 7. No clue where the variable 'c' comes from. 8. No clue where the type 'E' comes from. 9. 'R' is a type, not an instance. 10. I suspect it has something to do with UTF encodings, but there is no clue. This one is missing some docs too: http://dlang.org/phobos/std_math.html#abs
Re: Worst Phobos documentation evar!
On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 10:17:26PM +0200, ketmar via Digitalmars-d wrote: On Wed, 31 Dec 2014 10:59:32 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 4:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. You can not like a car's suspension but still like its engine. but 'make' is a failure in every aspect, especially GNU make. bwah, build tool that can't do autoimatic dependency tracking? you must be joking. Yeah no kidding. How do I hate make? Let me count the ways: 1) Recursive make considered harmful. (Google it.) 2) Non-reproducible builds -- you have to make clean; make, just to be absolutely sure your build is correct (defeats the purpose of a build tool, really -- might as well use a shell script of compiler commands). 3) Changing compile flags in a makefile does not trigger rebuilding of all affected targets. You're on your own to kick make into rebuilding what's needed. Usually, this means yet another `make clean; make`. Which doesn't always work -- see (6). A great source of heisenbugs. 4) Unnecessary rebuilds -- if you edit a comment in a header file, it causes a waterfall effect in rebuilding everything that #include's it, and even though all of the .o files produced are identical to those from the previous run, make is oblivious to this fact, and wastes time linking them all and cascading even more rebuilds that depend on the link products, etc., etc.. 5) Timestamps are unreliable -- accidentally touching the timestamp of a header file included by everything (without changing its contents) will cause the entire tree to be rebuilt. Timestamps over NFS may be inconsistent, causing make to randomly rebuild files that don't need to be rebuilt and skip files that do. 6) Dependency scanning is O(n). Not scalable. 7) No built-in cleanup function -- everybody writes their own `make clean` rules, which are inevitably wrong (`rm -rf *.o *.so`, but what if you have an .so that isn't generated by the build?) or incomplete (oops, forgot to delete the .c file generated by bison). This, coupled with (2) and (3), leads to heisenbugs where stale libraries from previous builds get linked into the executable, causing runtime bugs that don't exist in the source code. The solution? `make clean; make` and have another coffee break. Very productive. (Except when your make clean rules failed to delete said stale library, then it's time to \rm -rf and git clone a new repo.) 8) Implicit dependencies between source files require external tooling support (gcc -MF, which leaves stray .dep files all over the place, which `make clean` inevitably forgets to clean up, and which cause mistakes in the dependency tree when dependencies change and the .dep files aren't updated before make reads them). 9) Build parameters (e.g. compiler flags) are not well-encapsulated -- the global CFLAGS has to be tweaked, or you have to invent your own convoluted set of macros that are combined into the final compiler flags, which leads to a maintenance nightmare. 10) No support for out-of-tree builds (which are increasingly becoming clear that it's the superior way to go -- littering generated files in the same directories as source files inevitably leads to a gigantic mess). 11) No support for simultaneous variant builds such as cross-compiling for multiple architectures in the same run (unless you manually write this, which is a royal pain and extremely error-prone for something the build system *should* have taken care of for you) -- because of (7): all build variables are global and there's no way to reuse the same build rules with different target parameters. 12) Many common build tasks are not supported by the core make system, and require the user to reinvent the wheel, which results in large, convoluted, and fragile makefiles that stop working as soon as you try to do something that wasn't anticipated by the makefile authors. 13) Anachronistic syntax requirements, like distinguishing between spaces and tabs. Make is like C... it offers you raw functionality to shoot yourself in the foot and drown in dependency bugs, just like C offers you countless ways to have buffer overruns and dangling pointers. Yet people glory in their scars acquired over decades of pain, and build entire ecosystems around it, such that mention of any alternatives is resisted at best, and ridiculed and summarily dismissed at worst. What's baffling is that such a reaction is observed even in the D community, which, ostensibly, exists exactly because people are finally fed up with the
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 12:54:14PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 11:59 AM, Anon wrote: Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list. You don't have to. You can write it as: $(LIST A, B, C) or: $(LIST A, B, C ) [...] And what if you need commas in the list items? Oh right, $(COMMA). Very readable. T -- Be in denial for long enough, and one day you'll deny yourself of things you wish you hadn't.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning. Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). T -- If it breaks, you get to keep both pieces. -- Software disclaimer notice
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 12:40:20 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 7:13 AM, Jacob Carlborg wrote: I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing documentation for code. Not web sites, not books, but documentation for code. Documentation for code winds up on a web site. finally, i got your point. D is *your* *personal* *project*. not more, not less. it something is handy for you, it will be in D, and it doesn't matter how much other people arguing about changing it. if something is of no use for you, it would be a miracle to see it in D, even when the code is ready and almost anyone who cares about the thing anough wrote yes, do it! and i'm not talking about Ddoc here. and about Ddoc/markdown issue: the quoted sentense says it all. you want Ddoc to be able to produce websites. and you don't care if some other people think that Ddoc was invented for documenting the source code. you know, documenting sources implies easy reading by human without preprocesing. and easy human-readable format is easy to write. but yes, it can't create a cool website for you. nor it is good for DTP. you keep inventing artificial samples to show that one still has to use escaping in markdown. you know, looking at Ddoc, which consists mostly of visual noise, i can tell you that markdown is god-given immortal purity. yet i got the idea: Ddoc is for websites, not for API documentation. it happens to understand some D, but the primary goal is to create website. ok. we just misunderstood why Ddoc is here. i appreciate all your hard work on D (and on C/C++ compilers too, which i was used from time to time). but do you really want D to be a widely used language? seems that you are thinking about some future users, who will surely need to write a complex documents right in the D source code, so Ddoc must resemble DTP languages. that they (future users) will write alot of code and so we can't break that unwritten code by changing the language now. and so on. what you seem to miss here is that it's the current D users who spreading a word. make D better for current passionate users, and you may get those future users in the future. make D great, but frustrating for current passionate users, and you will get no future users at all, 'cause there will be nobody to spread a word about D. i, for myself, can't see why i have to endure annoyance in the name of future users. those future users did nothing for me, except making D frustrating. the thing is that future users will have to take what we giving 'em, not we have to take something that *might* please those future users. do you think that vibe.d is a valuable project? Sönke wants property enforcement syntax, for example. just ask him! and patch for that syntax is already here. that patch works, my DMD build using it. yet Sönke will not come here to argue for this feature for month (or years?), he is busy developing vibe.d (and other things). Sönke is a real user with a real project. he can live without property enforcement, but... besides, enforcing property syntax will solve the bug with delegate properties, where they need `()()` to really call the delegate. and we have dfix which can be extended to automatically fix user code. and what about tuple syntax? two years passed since PR was submitted. isn't it enough to stop thinking about how accepting that PR will close the opportunity to invent better syntax in the future and just accept it? two years of stagnation is enough to see that this feature is not at the top of priority list and you and Andrei will *always* have more important tasks to do. so just merge it and forget! (yes, i know that it can't be merged right now without rebasing; seems that we simply lost it) sorry. i hate new years. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
Ary Borenszweig a...@esperanto.org.ar wrote: On 12/31/14 9:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o)
Re: Worst Phobos documentation evar!
On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning. Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). You can, of course, occasionally look at the warnings :-)
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 09:23:58PM +, Andrei Alexandrescu via Digitalmars-d wrote: Ary Borenszweig a...@esperanto.org.ar wrote: On 12/31/14 9:17 AM, Jacob Carlborg wrote: On 2014-12-30 02:51, Walter Bright wrote: (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.) make has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like make I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) Yeah, just like D is still floundering in obscurity while inferior languages like C/C++ continue to flourish. *shrug* T -- There are four kinds of lies: lies, damn lies, and statistics.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 01:26:50PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote: On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote: This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now? Just ignore the warning. Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). You can, of course, occasionally look at the warnings :-) Of course. But it would be nice if this wasn't necessary in the first place. :-) Yes, yes, I know, where's the PR... I'll get to it! This week just isn't a good time for that, too many things going on IRL. I'm planning to submit some ddoc-related PRs in the near future; it would be a good time to fold this one in too. T -- Famous last words: I *think* this will work...
Re: Worst Phobos documentation evar!
On 12/31/2014 12:55 PM, Ary Borenszweig wrote:
Definitely, because Markdown is not a macro system, it's a documentation tool.
I write a lot of documentation. A macro system has saved enormous amounts of
effort. Night and day, really. Not having a macro system is like using a
programming language that does not have functions.
Ketmar, for example, complained mightily about Ddoc markup. I suggested he
simply email me the Phobos documentation he wants to write, and I'd mark it up
for him and submit the PRs. He admitted he is not interested in actually writing
any documentation. Ddoc is not the real issue, at least for him.
I'll extend the same offer to you. Email me the fixed Phobos docs. I'll mark
them up and submit PRs.
The thing is, with Ddoc you don't actually have to write any markup. You can
write:
/
This function does blah, blah, blah.
Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly.
Params:
x = the awesome input value
Returns:
insightful description of the return value
Example:
---
int foo(int x) { ... stunning D code ... }
---
***/
Re: Worst Phobos documentation evar!
On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. And Markdown never needs escapes. Right. :-)
Re: Worst Phobos documentation evar!
On 12/31/2014 12:54 PM, Ary Borenszweig wrote: Which still look readable (and the backslash is just one character of noise so it's also not that bad). (Then you've never tried to use regex string literals in C code.) C++ would not have added raw string literal syntax if this was not an issue. It was a welcome improvement from anyone I've heard comment on it.
Re: Worst Phobos documentation evar!
On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. And Markdown never needs escapes. Right. :-) It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more. T -- In theory, software is implemented according to the design that has been carefully worked out beforehand. In practice, design documents are written after the fact to describe the sorry mess that has gone on before.
Re: Worst Phobos documentation evar!
On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote: that still will be MUCH better than Ddoc. After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it.
Re: Worst Phobos documentation evar!
On 12/31/2014 12:49 PM, Ary Borenszweig wrote: Compare \* to $(STAR) I found two instances of $(COMMA) across the Phobos sources, and neither were necessary.
Re: Worst Phobos documentation evar!
On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it.
Re: Worst Phobos documentation evar!
On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: Yeah no kidding. How do I hate make? Let me count the ways: Ironically, none of your points mention the macro system.
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:14:46 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it. nake build system, first link from google: Nake is a magic task runner tool for .NET. It's a hybrid of Shovel and Rake. The DSL for defining tasks is uniquely minimal and it's just plain C# code! signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:19:00 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: Yeah no kidding. How do I hate make? Let me count the ways: Ironically, none of your points mention the macro system. that's 'cause 'make' doesn't need any. it's either enough to have envvars for simple tool, or you need a scripting language for complex extensible tool. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 14:10:06 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote: that still will be MUCH better than Ddoc. After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it. what use for me in such documentation? i can do Ddoc myself, i just can't read the result. what i want is readable documentation in .d files, without any preprocessing. Ddoc can't do that. so i can't see any sense in investing time to write documentation which then will be uglified by Ddoc. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei Alexandrescu wrote: Ary Borenszweig a...@esperanto.org.ar wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) What!! Rake is used by every Rails project out there. Thousands of more projects than D projects. -- /Jacob Carlborg
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 22:37:08 + Jacob Carlborg via Digitalmars-d digitalmars-d@puremagic.com wrote: On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei Alexandrescu wrote: Ary Borenszweig a...@esperanto.org.ar wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) What!! Rake is used by every Rails project out there. Thousands of more projects than D projects. and not only rails. mkvtools_nix using rake too, but it's pure C++ project. signature.asc Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/14 7:14 PM, Walter Bright wrote: On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it. Oh, it's for Nimrod (Now Nim)
Re: Worst Phobos documentation evar!
On 12/31/14 6:46 PM, Walter Bright wrote:
On 12/31/2014 12:55 PM, Ary Borenszweig wrote:
Definitely, because Markdown is not a macro system, it's a
documentation tool.
I write a lot of documentation. A macro system has saved enormous
amounts of effort. Night and day, really. Not having a macro system is
like using a programming language that does not have functions.
Ketmar, for example, complained mightily about Ddoc markup. I suggested
he simply email me the Phobos documentation he wants to write, and I'd
mark it up for him and submit the PRs. He admitted he is not interested
in actually writing any documentation. Ddoc is not the real issue, at
least for him.
I'll extend the same offer to you. Email me the fixed Phobos docs. I'll
mark them up and submit PRs.
The thing is, with Ddoc you don't actually have to write any markup. You
can write:
/
This function does blah, blah, blah.
Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly.
Params:
x = the awesome input value
Returns:
insightful description of the return value
Example:
---
int foo(int x) { ... stunning D code ... }
---
***/
You are right. I browsed some phobo's code and saw the documentation, it
looks clean and nice. The only exception is std.algorithm which is full
of macros and barely readable.
So where is that other macro code? The one that has $(BLANKLINE) or
$(COMMA) or $(DASH) and why is it needed?
Re: Worst Phobos documentation evar!
On Thu, Jan 01, 2015 at 12:26:04AM +0200, ketmar via Digitalmars-d wrote: On Wed, 31 Dec 2014 14:19:00 -0800 Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote: On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote: Yeah no kidding. How do I hate make? Let me count the ways: Ironically, none of your points mention the macro system. that's 'cause 'make' doesn't need any. it's either enough to have envvars for simple tool, or you need a scripting language for complex extensible tool. The macro system in make is so bad, it shouldn't need an explicit mention to be obvious that it's bad. Besides, macros are where the various flavors of make differ the most anyway, so anyone who wants anything resembling a cross-platform makefile should only use the most basic of macro functions and forego the actually-useful stuff. T -- Written on the window of a clothing store: No shirt, no shoes, no service.
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig wrote: You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed? IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added. One more fundamental issue with inline docs is not markup language but lack of any simple way to inherit / refer existing documentation entries. There is ditto but no same as in base method or same as for symbol X.
Re: Worst Phobos documentation evar!
On 12/31/14 7:43 PM, Ary Borenszweig wrote: On 12/31/14 7:14 PM, Walter Bright wrote: On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote: And it's no wonder why there are so many alternatives (rake, nake, etc.) ... Neither of which successful :o) I googled nake and couldn't find any references to it. Oh, it's for Nimrod (Now Nim) This one: https://github.com/fowlmouth/nake I'm not saying that it's popular, but people keep inventing things to avoid makefiles (and I think it's good to have this for a language).
Re: Worst Phobos documentation evar!
On 12/31/14 7:46 PM, Dicebot wrote: On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig wrote: You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed? IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added. It looks quite clean to me: https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd Except for the fact that instead of the familiar HTML tags there are macros. I see macros for: Paragraphs: $(P) Lists: $(UL), $(LI) Links: $(HTTP) These are very, very, vry common in documentation and sites. Couldn't DDoc provide nice, readable ways for dealing with these?
Re: Worst Phobos documentation evar!
On Wednesday, 31 December 2014 at 22:53:14 UTC, Ary Borenszweig wrote: It looks quite clean to me: https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd One of the very first lines: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description) $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers to data))) $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2 static-arrays, Static arrays))) $(TROW $(ARGS $(I type)[]), $(ARGS $(RELATIVE_LINK2 dynamic-arrays, Dynamic arrays))) $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map, Associative Arrays, Associative arrays))) ) I had no idea of what it is and how it will look like after doc generation until started checking each macro one by one. Similar stuff in md: | Kinds of Arrays| |--| | Syntax | Description | |--| |`type*` | [Pointers to data](/arrays.html#pointers) | |`type[integer]` | [Static arrays](/arrays.html#static-arrays) | // etc. it is just so much easier to work with : resembles actual generated layout, less noise from service symbols, no special macros for basic things. It may be somewhat less maintainable because everything is hard-coded but it is not something that changes casually.
Re: Worst Phobos documentation evar!
On 12/31/2014 2:47 PM, H. S. Teoh via Digitalmars-d wrote: The macro system in make is so bad, it shouldn't need an explicit mention to be obvious that it's bad. It's so bad you didn't mention it in the thread about the only similarity between make and Ddoc? C'mon. Besides, macros are where the various flavors of make differ the most anyway, Those are the various extensions people have added, and Ddoc copies none of those. That complaint about make macros is irrelevant to Ddoc.
Re: Worst Phobos documentation evar!
On 12/31/2014 2:47 PM, Ary Borenszweig wrote: I'm not saying that it's popular, but people keep inventing things to avoid makefiles (and I think it's good to have this for a language). People keep inventing new markup formats, too. (The first one I used, runoff, dates from the 70's.) I think the unix .man markup is even older.
Re: Worst Phobos documentation evar!
On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote:
i can do Ddoc myself, i just can't read the result.
/
This function does blah, blah, blah.
Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly.
Params:
x = the awesome input value
Returns:
insightful description of the return value
Example:
---
int foo(int x) { ... stunning D code ... }
---
***/
Re: Worst Phobos documentation evar!
On Wed, 31 Dec 2014 15:26:04 -0800
Walter Bright via Digitalmars-d digitalmars-d@puremagic.com wrote:
On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote:
i can do Ddoc myself, i just can't read the result.
/
This function does blah, blah, blah.
Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly.
Params:
x = the awesome input value
Returns:
insightful description of the return value
Example:
---
int foo(int x) { ... stunning D code ... }
---
***/
Implements the homonym function (also known as $(D accumulate), $(D
compress), $(D inject), or $(D foldl)) present in various programming
languages of functional flavor. The call $(D reduce!(fun)(seed,
range)) first assigns $(D seed) to an internal variable $(D result),
also called the accumulator. Then, for each element $(D x) in $(D
range), $(D result = fun(result, x)) gets evaluated. Finally, $(D
result) is returned. The one-argument version $(D reduce!(fun)(range))
works similarly, but it uses the first element of the range as the
seed (the range must be non-empty).
'cmon, wtf all that $(XXX) crap is? and with capitals, which distracts
from the actual text. ah, the following is even better:
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description)
)
$(LEADINGROW Searching
)
$(TR $(TDNW $(LREF all)) $(TD $(D all!a 0([1, 2, 3, 4])) returns $(D true)
because all elements are positive)
)
$(TR $(TDNW $(LREF any)) $(TD $(D any!a 0([1, 2, -3, -4])) returns $(D
true) because at least one element is positive)
)
$(TR $(TDNW $(LREF balancedParens)) $(TD $(D
balancedParens(((1 + 1) / 2))) returns $(D true) because the string
has balanced parentheses.)
)
$(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find(hello
world, boyerMooreFinder(or))) returns $(D orld) using the $(LUCKY
Boyer-Moore _algorithm).)
)
$(TR $(TDNW $(LREF canFind)) $(TD $(D canFind(hello world,
or)) returns $(D true).)
)
$(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal
to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1))
returns $(D 2) and $(D count!a 0([1, -3, 0])) returns $(D 1).)
)
$(TR $(TDNW $(LREF countUntil)) $(TD $(D countUntil(a, b))
returns the number of steps taken in $(D a) to reach $(D b); for
example, $(D countUntil(hello!, o)) returns $(D 4).)
)
$(TR $(TDNW $(LREF commonPrefix)) $(TD $(D commonPrefix(parakeet,
parachute)) returns $(D para).)
)
this goes on and on and on. this is just a line noise.
signature.asc
Description: PGP signature
Re: Worst Phobos documentation evar!
On 12/31/2014 2:05 PM, H. S. Teoh via Digitalmars-d wrote: On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d wrote: On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote: And what if you need commas in the list items? Oh right, $(COMMA). Very readable. And Markdown never needs escapes. Right. :-) It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more. As I said, I grepped the Phobos sources for $(COMMA), and found 2 instances, neither of which were necessary.
Re: Worst Phobos documentation evar!
On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote: ah, the following is even better: Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to.
Re: Worst Phobos documentation evar!
On 1/01/2015 4:23 a.m., Jacob Carlborg wrote: On 2014-12-30 06:13, Rikki Cattermole wrote: Hmm I have an idea. I wonder if I can get ddoc to generate json files. You would still need to write the documentation in Ddoc, which is what we're complaining about. I know. And btw currently ddoc cannot output json. I was considering some form of external tool that used e.g. DScanner to grab all the AST/comments and then parse them a little similar to DDoc just without the macros.
