On 2016-01-05 15:16, Adam D. Ruppe wrote:

> Interesting. Separating abstract is definitely a good idea since you
> kinda need to know that to implement.

I would really like to be able to write documentation for private methods as well, but hide them by default. I think it can be good when one is working on the implementation of a library.

> There's so much potential for class docs! Pity Phobos doesn't use them
> much though :(

Hehe, yeah.

-- 
/Jacob Carlborg

On Tuesday, 5 January 2016 at 16:06:17 UTC, Jacob Carlborg wrote:
> I would really like to be able to write documentation for private methods as well, but hide them by default. I think it can be good when one is working on the implementation of a library.

Right. In my thing, it is controlled by a flag when you run the generator. Same with undocumented methods, I sometimes like seeing them in the listing, so that's a flag too.

I'm almost happy enough with this code to post it btw, so you all can play with it yourselves soon. It was embarrassingly bad in its first week, I just hacked quickly but I refactored yesterday and it is starting to look like it wasn't written by letting my cat dance on the keyboard.

(Yes, I get embarrassed posting excessively ugly code to the Internet. I often don't like posting things until it it at least semi-stable alpha quality.)

On Tuesday, 5 January 2016 at 15:51:56 UTC, Nordlöw wrote:
> The mouse-over behaviour of CT- and RT-parameters is just really really cool! Thanks!

Awesome! That's just a little javascript but I feel it kinda adds a fourth dimension (the other three being width, height, and *color* on a website) that we can utilize.

Now that my refactor is almost complete, I'll be able to make this smarter too. The current highlighting is done by the javascript plus the code formatter, of all things, which is the wrong level to do smart lookups. Now that I have clean classes instead of spaghetti strings, the next steps are open to me!

On the listing, I'm using "simplified" prototypes and on the details page, I can start filling in the clickable things and recognize constraint patterns to translate them too.

On 2016-01-05 15:18, Andrei Alexandrescu wrote:

> That said, in a git-controlled directory things aren't that bad. "git
> clean -dfx" removes uncontrolled files and "git checkout" makes sure all
> files are present. Would you recommend switching to wildcards in our
> makefiles and assume people use git to keep their directories in good
> shape?

I would recommend against doing any form of cleaning. We don't want to remove untracked files that the user has added, for whatever reason. Instead "git ls-files" can be used. That will list all files tracked by git. Then of course adding wildcards, like *.d, where appropriate. Scoping to a single directory should also minimize unwanted files.

-- 
/Jacob Carlborg

On Tuesday, 5 January 2016 at 15:54:24 UTC, Andrei Alexandrescu wrote:
> On 01/05/2016 10:15 AM, bachmeier wrote:
>> The problem is not that my PR was (for practical purposes) rejected. As
>> an academic I deal with both sides of peer review all the time. The
>> problem is that I was forced to put so much time into it just to make a
>> suggestion. With Adam's project, I can send him an email with a
>> suggested change, and he can do as he wishes with it. It will take two
>> minutes of my time.
>
> I agree that the best aspect of Adam's system is Adam.
>
>
> Andrei

Yes, and because its lots of effort flowing into something that D is usually very fond of: Simplicity.
I remember looking at a part of the documentation and wanting to suggest a change of wording in a few sentences, since I felt like they didn't convey information clear enough, but after seeing that I would have to somehow best-guess my way through tons of macro syntax without clear indication on where to look for explanations of anything I bailed. Not about to spend half a day or a day to suggest changing three sentences and be told that they were fine as is. Sending Adam an E-Mail is something I totally would've done though :-)

On 01/05/2016 11:35 AM, default0 wrote:
>
> Yes, and because its lots of effort flowing into something that D is
> usually very fond of: Simplicity.

I'll be curious how the simplicity theme keeps when needed features get added. dlang.org started very simple and grew by accretion.

> I remember looking at a part of the documentation and wanting to suggest
> a change of wording in a few sentences, since I felt like they didn't
> convey information clear enough, but after seeing that I would have to
> somehow best-guess my way through tons of macro syntax without clear
> indication on where to look for explanations of anything I bailed. Not
> about to spend half a day or a day to suggest changing three sentences
> and be told that they were fine as is.

Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?

> Sending Adam an E-Mail is
> something I totally would've done though :-)

Again this goes back to Adam. Let's say we had a contributor Eve who'd gladly take emailed questions and suggestions and integrate them. Would that be as nice?


Andrei

On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
> Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?

I took a look at that link, and you know what would be (at least for me) more useful?

A "Let's write a doc example", for example: Creating a sample function and documented it, step by step. I really think that would be many times more useful and you see that pattern a lot not only for docs, but explain things, currently we saw this in another topic about writing a scalable chat using vibe.d!

JohnCK.

On Tuesday, 5 January 2016 at 18:34:20 UTC, JohnCK wrote:
> On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
>> Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?
>
> I took a look at that link, and you know what would be (at least for me) more useful?
>
> A "Let's write a doc example", for example: Creating a sample function and documented it, step by step. I really think that would be many times more useful and you see that pattern a lot not only for docs, but explain things, currently we saw this in another topic about writing a scalable chat using vibe.d!
>
> JohnCK.

+1

That wiki article is a great reference, but it's pretty daunting when someone just wants to make a small change.

On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
> Again this goes back to Adam. Let's say we had a contributor Eve who'd gladly take emailed questions and suggestions and integrate them. Would that be as nice?

Ohoh... Keep Eve out of it, she's got an Apple.

On Tuesday, 5 January 2016 at 15:54:24 UTC, Andrei Alexandrescu wrote:

> The text is imprecise, e.g. an equivalent call to `sort` really is `sort!((a, b) => less(transform(a), transform(b))`. All that detail needn't be present in the first paragraph, so there's a bit of an art in how you formulate simple sentences that are at the same time correct and informative.

That explanation is better than what I had.

> The second paragraph used to be the first (and only) one. Now it doesn't flow from the first one, it's jarring.

I left as much of the previous text as possible. I assumed that would create the least resistance to my changes.

Thanks for the review. I will make these changes when I have a lengthy block of free time.