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!

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!

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)

On Tue, Feb 27, 2018 at 03:07:10AM +0000, 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

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 !

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 <https://github.com/adamdruppe/adrdox> 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.

Tried with http://diamond.dpldocs.info/arsd.html and it gives a 404

On Tuesday, 27 February 2018 at 09:16:12 UTC, bauss wrote:
> On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
>> [...]
>
> Tried with http://diamond.dpldocs.info/arsd.html and it gives a 404

Nvm, I see how stupid I was.

On Tuesday, 27 February 2018 at 09:17:21 UTC, bauss wrote:
> On Tuesday, 27 February 2018 at 09:16:12 UTC, bauss wrote:
>> On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
>>> [...]
>>
>> Tried with http://diamond.dpldocs.info/arsd.html and it gives a 404
>
> Nvm, I see how stupid I was.

You were not stupid. You made a mistake. They're two different things.

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 <https://github.com/adamdruppe/adrdox> 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.

Awesome work. IDEs could use this, i don't know how yet but i'll maybe try something one day.

Are the doc persistent on your server ?
For example is http://iz.dpldocs.info/v0.6.4/iz.html here forever ?

On Tuesday, 27 February 2018 at 09:17:21 UTC, bauss wrote:
> Nvm, I see how stupid I was.

Nah, bad UX. I give myself some slack cuz I slapped this together in just a few spare hours over the weekend, but the error message also could have pointed you back to the site index.

That just took 3 minutes to change tho, now it says:

404. Try diamond.html as a starting point (and it is a link)