Re: Documentation for any* dub package, any version

[Martin Tschierschke via Digitalmars-d-announce]

On Tuesday, 27 February 2018 at 02:07:34 UTC, Norm wrote:
On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe 
wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.


[...]


This is really awesome. It would be really cool if this could 
feedback a coverage score to code.dlang.org that indicates the 
level of documentation in a library. Something like the % of 
functions/classes/modules that are documented and if there are 
any missing parameters/warnings during the parsing of docs.


Cheers,
Norm


+1000 !

Re: Documentation for any* dub package, any version

[H. S. Teoh via Digitalmars-d-announce]

On Tue, Feb 27, 2018 at 03:07:10AM +, psychoticRabbit via 
Digitalmars-d-announce wrote:
[...]
> Uhh? I don't get...why coders need to write documentation?
[...]

To communicate with other coders who will need to read and maintain the
code.

And by "other coders", of course, I mean yourself, 2 months later. :-D

If you've ever stared at some code you wrote 5 months ago (or worse, 15
years ago) and wondered, "who wrote this crap" or "what on earth what I
thinking about at the time?!", you'll know what I mean. :-P


T

-- 
The volume of a pizza of thickness a and radius z can be described by the 
following formula: pi zz a. -- Wouter Verhelst

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 19:30:38 UTC, WebFreak001 wrote:
amazing! I planned on adding a documentation tab in the current 
dub package overhaul, but I wasn't sure on where to get the 
data from, if I can add this to embed on the dub website (ala 
iframe) it would make a lot much easier! Could you maybe add an 
API endpoint to check if documentation is present (download & 
cache it if not there and check via that) so it will only show 
it optionally?


I'd say just always show the documentation tab/link. If it is 
broken, we can tell the package maintainer to fix it!


BTW the header now has links for the project homepage (if it has 
one), dub package, and git repo


http://vibe-d.dpldocs.info/vibe.core.drivers.libevent2_tcp.html

for example.

(docs generated already will not show this until i next clear the 
internal cache. prolly tomorrow)

Re: Documentation for any* dub package, any version

[psychoticRabbit via Digitalmars-d-announce]

On Tuesday, 27 February 2018 at 02:57:08 UTC, Adam D. Ruppe wrote:


Saturday morning, a user complained that several leading dub 
packages had poor documentation, if they could find it at all. 
That's changing, right now.


Before long, packages without docs are going to suffer. This 
will put pressure on authors to have *something* written, and 
I'm providing the lowest cost for greatest benefit to help your 
package succeed in the market.




Uhh? I don't get...why coders need to write documentation?

.. it doesn't make any sense.

stop this nonsense... at once!

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Tuesday, 27 February 2018 at 01:53:23 UTC, H. S. Teoh wrote:
It's a sorry state of affairs.  I dream of the day when I can 
just write code and documentation as-is, and downstream users 
can just use whatever doc formatting system they like and it 
will all Just Work(tm).


Join me, and together, we can rule the D-alaxy as coder and 
coder! https://www.youtube.com/watch?v=tzvY1OzoDbQ



But I'm not holding my breath for that to materialize.


Saturday morning, a user complained that several leading dub 
packages had poor documentation, if they could find it at all. 
That's changing, right now.


Before long, packages without docs are going to suffer. This will 
put pressure on authors to have *something* written, and I'm 
providing the lowest cost for greatest benefit to help your 
package succeed in the market.


In the end? Everybody wins.

Package authors get an automatic documentation build that is 
discoverable, legible, searchable and navigable. They can just 
write plain text (or some markdown) and it just works, or go 
deeper and use the advanced toolset I have to offer, allowing 
them to focus on documenting their libraries instead of 
struggling with the documentation system.


Package users get links that work and can more quickly locate and 
evaluate packages before using them, and use them more 
effectively after deciding to go forward.


And, of course, I win because I get power! UNLIMITED POWER!

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

On Tuesday, February 27, 2018 02:26:49 Adam D. Ruppe via Digitalmars-d-
announce wrote:
> But even you, who know how to use ddoc very well and have
> obviously spent some time on it here, made trivial mistakes here
> that just don't happen with adrdox.

Any time you do something manually instead of it being automatic, there's a
risk of that.

And if adrdox works well for folks, then great. Personally, I'd like to
stick to the official tool, especially when I'm writing something that might
make it into Phobos (though like Phobos, I was forced to add a helper
program in order to deal with stuff like the navigation bar), but there are
definitely aspects of it which make it harder to use than adrdox or ddox.

Thanks for pointing out those mistakes.

- Jonathan M Davis

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Tuesday, 27 February 2018 at 02:07:34 UTC, Norm wrote:
This is really awesome. It would be really cool if this could 
feedback a coverage score to code.dlang.org that indicates the 
level of documentation in a library. Something like the % of 
functions/classes/modules that are documented and if there are 
any missing parameters/warnings during the parsing of docs.


Maybe, though I don't think computer analysis can say if docs are 
good (at least not with simple code I'd be likely to write). Like 
there might be a lot of public functions deliberately 
undocumented because they are of alpha quality and not supported, 
but still available in case advanced users want to dive in.


But just having docs generated automatically that users can click 
on and peruse will give the human a chance to quickly and easily 
evaluate the package.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Tuesday, 27 February 2018 at 01:43:55 UTC, Jonathan M Davis 
wrote:
Well, then basically, projects are going to need to decide to 
go with adrdox over ddoc if they want clean documentation.


That's right, and I can't imagine anyone is going to put hours of 
work into ddoc when they can spend seconds just writing and have 
it just work on my site, including most common ddoc in addition 
to a good subset of markdown and, if they decide to dive a little 
bit deeper, can use my custom syntax custom-tailored to writing D 
documentation quickly and easily like [link].


https://www.youtube.com/watch?v=Ak516vtDTEA

They'll probably get better documentation with adrdox than the 
default ddoc if they do nothing, but any project that actually 
goes to the effort of having nice looking documentation is 
going to fall flat on its face with adrdox unless it buys into 
adrdox whole hog.


Eh, that's not true. I am *very* compatible with Phobos (have you 
use dpldocs.info before? 9/10 dentists agree, it is vastly 
superior to dlang.org, and the tenth dentist is paid to lie), and 
since most "nicer" ddoc borrows from the phobos definitions, most 
of them will just work too. I actually even just added your LREF2 
macro to the internal macro compatibility list, bringing my 
compatibly with your syntax to near-total.


BTW you misspelled "element" here:
http://dxml.dpldocs.info/source/dxml.dom.d.html#L119

On your version, third paragraph:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_dom.html#.DOMEntity

adrdox (my build here anyway, which knows the whole phobos tree 
too) caught that and issued a broken link warning. Did ddoc? I 
already know the answer.


Of course, if you were using adrdox syntax, that mistake wouldn't 
have happened in the first place, instead of writing:


  $(REF_ALTTEXT EntityType.elementStart, EntityType.elmentStart, 
dxml, parser)


You would have simply wrote [EntityType.elementStart] and not had 
to repeat yourself telling the compiler what it already knows (in 
a bizarre order, no less).



Of course, even with the broken link, the adrdox result is usable:

http://dxml.dpldocs.info/dxml.dom.parseDOM.2.html

links to:
http://dxml.dpldocs.info/dxml.parser.EntityType.html#elmentStart

and you can see it in the table.

Whereas the ddoc link goes to:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_parser.html#.EntityType.elmentStart

where the anchor is who-knows-where.


Moreover, look at this:
http://dxml.dpldocs.info/dxml.util.asNormalized.html

"combines parseStdEntityRef and parseCharRef along with 
processing for $(DCODE_STRING '\r') to"


and compare with:
http://jmdavisprog.com/docs/dxml/0.2.3/dxml_util.html#.asNormalized

"combines parseStdEntityRef and parseCharRef along with 
processing for to "



See something missing? Yes, you write DCODE_STRING instead of the 
definition of D_CODE_STRING and ddoc swallowed your text. (Yes, I 
know you can define ddoc to output undefined macros, just like 
adrdox does. But it doesn't by default, so a typo in a macro name 
means text just ~disappears~.)



And again, that is unlikely to have happened if you just used the 
standard backticks (`'\r'`) which don't render exactly the same 
but are good enough. ddoc supports them too, so this isn't even 
an adrdox thing... but I'd argue that merely having user-defined 
macros makes you more likely to try to use them, increasing the 
likelihood for mistakes like this. That's the main reason why I 
decided to simply not support them, the cost outweighs the 
benefits.




I don't say this to pick on you - you have some of the nicest 
ddoc I have ever seen, and you actually make the effort to write 
it all up in the first place.


But even you, who know how to use ddoc very well and have 
obviously spent some time on it here, made trivial mistakes here 
that just don't happen with adrdox.

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

On Monday, February 26, 2018 17:53:23 H. S. Teoh via Digitalmars-d-announce 
wrote:
> On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via
> Digitalmars-d-announce wrote: [...]
>
> > Well, then basically, projects are going to need to decide to go with
> > adrdox over ddoc if they want clean documentation. They'll probably
> > get better documentation with adrdox than the default ddoc if they do
> > nothing, but any project that actually goes to the effort of having
> > nice looking documentation is going to fall flat on its face with
> > adrdox unless it buys into adrdox whole hog.
> >
> > dxml would be a prime example of a project that won't work with adrdox
> > though given that it tries to emulate what Phobos has done with its
> > documentation, and many of the macros are the same, which should
> > minimize how much the documentation will have to be mucked with if it
> > ever ends up in Phobos, but that means that it is very much not
> > vanilla ddoc, let alone adrdox.
>
> [...]
>
> It's a sorry state of affairs.  I dream of the day when I can just write
> code and documentation as-is, and downstream users can just use whatever
> doc formatting system they like and it will all Just Work(tm).
>
> Basically, it requires a standard way of writing documentation that
> every backend tool understands and supports, be it ddoc or adrdox or
> whatever else you fancy.  But I'm not holding my breath for that to
> materialize.

Basically, it requires that you do _nothing_ by hand - so no ddoc macros -
and the tools figure it all out from the json output from the compiler. As
soon as you start marking up the documentation in any way, unless it's a way
that _all_ of the tools understand, it's not going to work. And doing
something like using macros to generate links like Phobos or dxml do is
instant death to that - the same goes with adrdox's markup for links, though
that is more automated, so it would be possible to make that understood by
more tools, whereas links for ddoc macros are too specific for that.

ddoc does a good job of doing some of the basics, and it provides a way to
have really nice documentation if you go the extra mile (including using
additional tools to generate stuff like navigation bars to navigate between
modules), but it utterly fails as a way to just generate really nice
documentation. For that, it would have to process the entire project at once
and not be file-centric like it is now. It would also have to do more for
you and leave less to macros.

Ultimately, I think that it's going to be up to each project to choose which
tool or combination of tools to use to generate their documentation, and any
time that anyone doesn't bother to figure that out, you're going to get a
subpar result - though ddox and adrdox will likely result in better
documentation with no effort than pure ddoc will, since they do stuff like
generate the navigation bar for you.

Once I've cleaned it up and documented it, I'm actually planning on
releasing what I did for dxml as project on github so that it will be
possible for anyone's project to easily have documentation like dxml does
(including the navigation bar), though like Phobos, it requires manually
using linking macros, since it's just ddoc with a helper program to generate
the pieces that you can't do with macros. If you want documentation without
any attempt to mark anything up, ddox is probably your best bet.

- Jonathan M Davis

Re: Documentation for any* dub package, any version

[Norm via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.


[...]


This is really awesome. It would be really cool if this could 
feedback a coverage score to code.dlang.org that indicates the 
level of documentation in a library. Something like the % of 
functions/classes/modules that are documented and if there are 
any missing parameters/warnings during the parsing of docs.


Cheers,
Norm

Re: Documentation for any* dub package, any version

[H. S. Teoh via Digitalmars-d-announce]

On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via 
Digitalmars-d-announce wrote:
[...]
> Well, then basically, projects are going to need to decide to go with
> adrdox over ddoc if they want clean documentation. They'll probably
> get better documentation with adrdox than the default ddoc if they do
> nothing, but any project that actually goes to the effort of having
> nice looking documentation is going to fall flat on its face with
> adrdox unless it buys into adrdox whole hog.
> 
> dxml would be a prime example of a project that won't work with adrdox
> though given that it tries to emulate what Phobos has done with its
> documentation, and many of the macros are the same, which should
> minimize how much the documentation will have to be mucked with if it
> ever ends up in Phobos, but that means that it is very much not
> vanilla ddoc, let alone adrdox.
[...]

It's a sorry state of affairs.  I dream of the day when I can just write
code and documentation as-is, and downstream users can just use whatever
doc formatting system they like and it will all Just Work(tm).

Basically, it requires a standard way of writing documentation that
every backend tool understands and supports, be it ddoc or adrdox or
whatever else you fancy.  But I'm not holding my breath for that to
materialize.


T

-- 
Unix is my IDE. -- Justin Whear

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

On Monday, February 26, 2018 19:51:27 Adam D. Ruppe via Digitalmars-d-
announce wrote:
> On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis
>
> wrote:
> > Yeah. Any project that uses .ddoc files to define additional
> > macros isn't going to work properly
>
> It is actually more than that: I don't support user-defined ddoc
> macros at all. About 3/4 of the ones I've seen are just link
> macros instead of everyone creating their own random mix
> (like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF,
> PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in,
> simple, unified syntax: [symbol|alt text] where alt text is
> optional and symbol is looked up according to D scope rules. (you
> can also define custom symbols for things like author name links).
>
> I link to the source automatically too, including to the specific
> line of the correct overload for functions, so no need for macros
> to do those.
>
> Much easier to write in code: no more need to remember what this
> project decided to name its macro.
>
> (keep in mind that adrdox is explicitly NOT ddoc. I dropped a few
> ddoc misfeatures and modified some in a non-compatible way. I've
> given up on trying to save ddoc, it is rotten to the core.)

Well, then basically, projects are going to need to decide to go with adrdox
over ddoc if they want clean documentation. They'll probably get better
documentation with adrdox than the default ddoc if they do nothing, but any
project that actually goes to the effort of having nice looking
documentation is going to fall flat on its face with adrdox unless it buys
into adrdox whole hog.

dxml would be a prime example of a project that won't work with adrdox
though given that it tries to emulate what Phobos has done with its
documentation, and many of the macros are the same, which should minimize
how much the documentation will have to be mucked with if it ever ends up in
Phobos, but that means that it is very much not vanilla ddoc, let alone
adrdox.

- Jonathan M Davis

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 21:16:07 UTC, Antonio Corbi wrote:
Trying it onto gtk-d got an error saying to send you the 
failing link, so here you are :


gtk-d is actually just too big for this, so it timed out. But I 
also already made gtkd docs on the main site:


http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html


gtk is a bit of a special case in part because of its sheer size 
and in part because it uses C names and special gtk syntax. The 
generator can translate it though - it just needs a special 
command line arg which right now means I do it manually.

Re: Documentation for any* dub package, any version

[Antonio Corbi via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.


Hi Adam!

Thanks for this superb work!

Trying it onto gtk-d got an error saying to send you the failing 
link, so here you are :


http://gtk-d.dpldocs.info/cairo.html

A. Corbi

Re: An optional/maybe type with range semantics

[Meta via Digitalmars-d-announce]

On Monday, 26 February 2018 at 20:04:14 UTC, aliak wrote:
Meta: Is this your stuff btw? -> 
https://github.com/skirino/d-option :) me thinks I may have 
gotten some inspiration from you if so, so thanks!


Nope. I'm MetaLang on Github.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 20:15:13 UTC, aliak wrote:
Awesome. good start at least, and just to throw an approach out 
there for your consideration, a .adrdox.yml file with a 
include/exclude/style/etc keys might be a good way to go.


Yeah, that's basically what I was thinking (though not yml, I'd 
use a sane, well-support language. actually I'd probably just use 
xml.)


Great! Think I'll give the skeleton/style a hack at some point 
indeed.


Well, that's if you download and host the stuff yourself. Though 
my css file is kinda intertwined, it has the mobile responsive 
stuff in there next to content presentation and syntax highlight 
colors, etc


Maybe if it's a central host then styling should just be 
homogeneous across the board as well for consistency and all?


yeah, maybe that too.

Re: Documentation for any* dub package, any version

[aliak via Digitalmars-d-announce]

On Monday, 26 February 2018 at 18:17:51 UTC, Adam D. Ruppe wrote:
Oh, fixed now. since there's no ddoc at all in that file, it 
should have been skipped, I just had a testing "return true;" 
in the method I forgot to remove.


Nice :D Looks good.

ketmar sent me a patch to parse a .adrdox_ignore file, in the 
same format as gitignore, which I merged but haven't pushed to 
that server yet. I'm not sure that's the exact approach I want 
to take, but something like that will be an option soon too if 
the default doesn't work out.


Awesome. good start at least, and just to throw an approach out 
there for your consideration, a .adrdox.yml file with a 
include/exclude/style/etc keys might be a good way to go.


Yeah, I just need to decide how I want that to look in the repo 
too (if you download adrdox yourself, you can change the 
skeleton.html and style.css files locally. style.css is a bit 
of a mess tho but it can be done, i did a dark color scheme 
here to use as a test. but how to do that on the central host? 
idk yet, maybe it can read a custom file out of the git repo, 
or add some option to dub.json.). but that will prolly be a 
week or two before i get around to it.


Great! Think I'll give the skeleton/style a hack at some point 
indeed. Maybe if it's a central host then styling should just be 
homogeneous across the board as well for consistency and all?


Cheers

Re: An optional/maybe type with range semantics

[aliak via Digitalmars-d-announce]

On Monday, 26 February 2018 at 16:02:58 UTC, Dukc wrote:


I kinda start to see the idea... Granted, nullable is in a way 
a range that can hold exactly one or exactly zero elements. Not 
a bad idea at all.


Aye, ranges do not need nullability indeed. Optional doesn't need 
to adhere to the range spec of course, but it does provide some 
conveniences. There's a d-forum thread here on it actually: 
https://forum.dlang.org/thread/l87ivq$263r$1...@digitalmars.com


There's a link in there on scala's optional type which is a fun 
read.


Here's a bit on the current "brokenness" nature of java's 
optional: 
https://developer.atlassian.com/blog/2015/08/optional-broken/


I like how it specifies intent (on the c++ optional): 
https://www.fluentcpp.com/2016/11/24/clearer-interfaces-with-optionalt/


Boost has a fun write-up on the motivation and design behind its 
optional type (which was incorporated in to the c++ standard): 
http://www.boost.org/doc/libs/1_66_0/libs/optional/doc/html/index.html


Meta: Is this your stuff btw? -> 
https://github.com/skirino/d-option :) me thinks I may have 
gotten some inspiration from you if so, so thanks!




But shouldn't it store the value internally as a pointer, not 
as an array, to save a bit space? When empty, it would point to 
null.


Guess I could do a pointer and call new when i need to store a 
value instead. Or maybe it's better to do it like above and store 
as value type with default value and a boolean at the site. Not 
sure.

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis 
wrote:
Yeah. Any project that uses .ddoc files to define additional 
macros isn't going to work properly


It is actually more than that: I don't support user-defined ddoc 
macros at all. About 3/4 of the ones I've seen are just link 
macros instead of everyone creating their own random mix 
(like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF, 
PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in, 
simple, unified syntax: [symbol|alt text] where alt text is 
optional and symbol is looked up according to D scope rules. (you 
can also define custom symbols for things like author name links).


I link to the source automatically too, including to the specific 
line of the correct overload for functions, so no need for macros 
to do those.


Much easier to write in code: no more need to remember what this 
project decided to name its macro.


(keep in mind that adrdox is explicitly NOT ddoc. I dropped a few 
ddoc misfeatures and modified some in a non-compatible way. I've 
given up on trying to save ddoc, it is rotten to the core.)

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 19:47:29 UTC, Jesse Phillips wrote:
It also would be good for you to like to the Dub page and Git 
Repo.


Yeah, its on my list. The project homepage from the dub.json too.

Couldn't you provide a robots.txt file which Google should 
honor so that 'nofollow' isn't required?


yeah but i don't mind them crawling pages that already exist and 
are linked from other websites where the author has agreed to 
support it somehow.

Re: Documentation for any* dub package, any version

[Jesse Phillips via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:

I'd like to get the code.dlang.org folks to add the correct 
link to the main package site so people can easily discover 
this just put nofollow on it plz so google doesn't trigger 
generation of pages people don't actually need (the lazy 
generation + caching allows me to host this on a cheap VPS)


It also would be good for you to like to the Dub page and Git 
Repo.


Couldn't you provide a robots.txt file which Google should honor 
so that 'nofollow' isn't required?

Re: Documentation for any* dub package, any version

[WebFreak001 via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.


[...]


amazing! I planned on adding a documentation tab in the current 
dub package overhaul, but I wasn't sure on where to get the data 
from, if I can add this to embed on the dub website (ala iframe) 
it would make a lot much easier! Could you maybe add an API 
endpoint to check if documentation is present (download & cache 
it if not there and check via that) so it will only show it 
optionally?

Re: Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

On Monday, 26 February 2018 at 15:21:55 UTC, aliak wrote:
Questions: Tried it with optional and undocumented stuff is 
also shown.


Oh, fixed now. since there's no ddoc at all in that file, it 
should have been skipped, I just had a testing "return true;" in 
the method I forgot to remove.


And then for the internal ones, I also just made it consider any 
module/package called "internal" to be automatically skipped too 
because that's a fairly common pattern.


So try this now:
http://optional.dpldocs.info/optional.html

it it cuts those other modules out.

What's the recommended way to not have some modules in there at 
this time, if any?


ketmar sent me a patch to parse a .adrdox_ignore file, in the 
same format as gitignore, which I merged but haven't pushed to 
that server yet. I'm not sure that's the exact approach I want to 
take, but something like that will be an option soon too if the 
default doesn't work out.


Thanks for this, with theming support I think I'd switch to 
this in me personal repos at least.


Yeah, I just need to decide how I want that to look in the repo 
too (if you download adrdox yourself, you can change the 
skeleton.html and style.css files locally. style.css is a bit of 
a mess tho but it can be done, i did a dark color scheme here to 
use as a test. but how to do that on the central host? idk yet, 
maybe it can read a custom file out of the git repo, or add some 
option to dub.json.). but that will prolly be a week or two 
before i get around to it.

Re: An optional/maybe type with range semantics

[Dukc via Digitalmars-d-announce]

On Monday, 26 February 2018 at 15:27:11 UTC, Meta wrote:
The idea is to treat `Option!T` as a regular input range so it 
can be used with all the regular range algorithms without 
special casing it. You're right in that the null/non-null 
dichotomy is equivalent to the notion of a range being empty or 
non-empty.


I kinda start to see the idea... Granted, nullable is in a way a 
range that can hold exactly one or exactly zero elements. Not a 
bad idea at all.


But shouldn't it store the value internally as a pointer, not as 
an array, to save a bit space? When empty, it would point to null.

Re: Documentation for any* dub package, any version

[Jonathan M Davis via Digitalmars-d-announce]

On Monday, February 26, 2018 14:59:07 Adam D. Ruppe via Digitalmars-d-
announce wrote:
> It isn't 100% compatible with ddoc. For example, this
> user-defined macro was not expanded:
> http://dxml.dpldocs.info/dxml.dom.html#source

Yeah. Any project that uses .ddoc files to define additional macros isn't
going to work properly, whereas projects that make no attempt to define
stuff like linking macros and just have documentation using the predefined
macros should work just fine.

- Jonathan M Davis

Re: An optional/maybe type with range semantics

[Meta via Digitalmars-d-announce]

On Monday, 26 February 2018 at 15:21:27 UTC, Dukc wrote:
Honestly, I fail to see the idea behind this... Ranges do not 
need any nullability on top of them IMO, because an empty range 
can already be used to denote a kind of "default", "unassigned" 
or "nothing" - type of value.


On the other hand I may just be missing something... do you 
have an example use case for this where phobos ranges would be 
a bad option?


Anyway, good effort.


The idea is to treat `Option!T` as a regular input range so it 
can be used with all the regular range algorithms without special 
casing it. You're right in that the null/non-null dichotomy is 
equivalent to the notion of a range being empty or non-empty.

Re: Documentation for any* dub package, any version

[aliak via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.


Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
generate docs for dub package projectname, version X.Y.Z. (If 
you don't specify a version, it will pull the master branch.)


For example:

http://arsd-official.dpldocs.info/arsd.html

master branch for the arsd-official package

or:

http://dplug.dpldocs.info/v6.0.22/dplug.html

6.0.22 of the dplug package.

etc.

I'd like to get the code.dlang.org folks to add the correct 
link to the main package site so people can easily discover 
this just put nofollow on it plz so google doesn't trigger 
generation of pages people don't actually need (the lazy 
generation + caching allows me to host this on a cheap VPS)



It builds the docs using my own doc generator 
 which pulls embedded doc 
comments out of the source.


It isn't 100% compatible with ddoc. For example, this 
user-defined macro was not expanded: 
http://dxml.dpldocs.info/dxml.dom.html#source


But, it builds 99% of Phobos so it can probably build your 
project too! And get the ease of adrdox navigation and 
legibility.


Moreover, if you want to embrace it, you can use all the 
features described here: 
http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
for the LaTeX math generation (that's not installed on the dub 
doc server I set up).


You can group functions like seen here: 
http://dpldocs.info/experimental-docs/arsd.nanovega.html and 
use some markdown syntax, and easy [reference] linking and more.




The generated docs may get some customization options in the 
future, like adding a logo, header nav links, or maybe tweaking 
the color scheme. It will probably also start reading 
.gitignore and perhaps a .adrdoxignore file soon to to exclude 
files from generation. I just need to decide the details first 
and it is time to work the day job right now and I want to 
announce sooner rather than later :)



* currently, only github code downloading is actually 
implemented.


This is awesome! Worked great. I use ddox right now (eg: 
https://aliak00.github.io/optional/) and your front page is way 
better and the source links are gold!


Questions: Tried it with optional and undocumented stuff is also 
shown. Will this be the default or? What's the recommended way to 
not have some modules in there at this time, if any?


Currently I have a internal.d (e.g. 
https://github.com/aliak00/optional/blob/master/source/optional/internal.d) which has public imports because I want to include it everywhere in my project and have all files have access to (though I think I may need to read up on access controls and modules cause I've just been winging it).


Thanks for this, with theming support I think I'd switch to this 
in me personal repos at least.


Cheers

Re: An optional/maybe type with range semantics

[Dukc via Digitalmars-d-announce]

On Sunday, 25 February 2018 at 18:03:35 UTC, aliak wrote:

Alo,

Just finished up a first take on an optional type for D. It's 
essentially a mix of Nullable and std.range.only, but with a 
lot more bells and whistles. I would love to hear any feedback 
on code, or features, or bad design or potential for better 
designs from anyone who's interested :)


Code: https://github.com/aliak00/optional
Dub: https://code.dlang.org/packages/optional
Docs: https://aliak00.github.io/optional/

Things to do:
* Handle dispatching of static fields/method (see code below)
* Implement flatmap/decide if flatmap should be in here
* Figure out what kind of range this should be (currently its 
just an input range - should it be more?)
* Implement some phobos algorithms as returning optionals (e.g. 
countUntil)


Anyway, here's some code to peak at a few of the supported 
features:


auto a = some(3);
auto b = a + 4; // opUnary/Binary/Equals (so far) supported

a = none;
a++ // noop

auto p = no!(int*);
assert(a == *p) // none == none
p = null;
assert(a == *p) // null handled

struct A {
  struct B { void g() {} }
  B f() { return B(); }
}

auto  b = no!(A*);
b.dispatch.f.g // dispatch is safe, noop

b = new A;
b.dispatch.f.g // makes calls now because non empty.

Cheers,
- Ali


Honestly, I fail to see the idea behind this... Ranges do not 
need any nullability on top of them IMO, because an empty range 
can already be used to denote a kind of "default", "unassigned" 
or "nothing" - type of value.


On the other hand I may just be missing something... do you have 
an example use case for this where phobos ranges would be a bad 
option?


Anyway, good effort.

Re: Documentation for any* dub package, any version

[Guillaume Piolat via Digitalmars-d-announce]

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
Many of you will already know this from the other thread or 
from my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub 
package.




This is very much awesome, much cleaner than generating docs 
locally imho.

Congrats!

I'd like to get the code.dlang.org folks to add the correct 
link to the main package site so people can easily discover 
this just put nofollow on it plz so google doesn't trigger 
generation of pages people don't actually need (the lazy 
generation + caching allows me to host this on a cheap VPS)


Perhaps a case robots.txt being useful for once?

Documentation for any* dub package, any version

[Adam D. Ruppe via Digitalmars-d-announce]

Many of you will already know this from the other thread or from 
my twitter, but I just added a on-demand downloader to my 
dpldocs.info domain to fetch and build docs for any* dub package.


Simply go to projectname.dpldocs.info/vX.Y.Z/ and it will 
generate docs for dub package projectname, version X.Y.Z. (If you 
don't specify a version, it will pull the master branch.)


For example:

http://arsd-official.dpldocs.info/arsd.html

master branch for the arsd-official package

or:

http://dplug.dpldocs.info/v6.0.22/dplug.html

6.0.22 of the dplug package.

etc.

I'd like to get the code.dlang.org folks to add the correct link 
to the main package site so people can easily discover this 
just put nofollow on it plz so google doesn't trigger generation 
of pages people don't actually need (the lazy generation + 
caching allows me to host this on a cheap VPS)



It builds the docs using my own doc generator 
 which pulls embedded doc 
comments out of the source.


It isn't 100% compatible with ddoc. For example, this 
user-defined macro was not expanded: 
http://dxml.dpldocs.info/dxml.dom.html#source


But, it builds 99% of Phobos so it can probably build your 
project too! And get the ease of adrdox navigation and legibility.


Moreover, if you want to embrace it, you can use all the features 
described here: 
http://dpldocs.info/experimental-docs/adrdox.syntax.html except 
for the LaTeX math generation (that's not installed on the dub 
doc server I set up).


You can group functions like seen here: 
http://dpldocs.info/experimental-docs/arsd.nanovega.html and use 
some markdown syntax, and easy [reference] linking and more.




The generated docs may get some customization options in the 
future, like adding a logo, header nav links, or maybe tweaking 
the color scheme. It will probably also start reading .gitignore 
and perhaps a .adrdoxignore file soon to to exclude files from 
generation. I just need to decide the details first and it is 
time to work the day job right now and I want to announce sooner 
rather than later :)



* currently, only github code downloading is actually implemented.