www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - API Documentation vs Library Reference

reply partypooper <pythonproof gmail.com> writes:
Personally currently in a stage of learning D I have found that 
[API Documentation](https://dlang.org/library/) is much more 
approachable and better structured than [Library 
Reference](https://dlang.org/phobos/index.html) maybe except for 
the modules by Mister Alexandresku, they are well structured even 
in the reference.

But the problem is that there is no any link to api documentation 
on the main page. And I actually found it by accident (maybe I'm 
just blind).
What do you think about structure of both of them and why there 
is one over the other?
Feb 21 2022
next sibling parent partypooper <pythonproof gmail.com> writes:
Forgot to add, that searching in the Api Library works as it 
should, not just googling like in the reference.
Feb 21 2022
prev sibling next sibling parent reply Mike Parker <aldacron gmail.com> writes:
On Monday, 21 February 2022 at 11:33:55 UTC, partypooper wrote:

 Personally currently in a stage of learning D I have found that 
 [API Documentation](https://dlang.org/library/) is much more 
 approachable and better structured than [Library 
 Reference](https://dlang.org/phobos/index.html) maybe except 
 for the modules by Mister Alexandresku, they are well 
 structured even in the reference.

 But the problem is that there is no any link to api 
 documentation on the main page. And I actually found it by 
 accident (maybe I'm just blind).
 What do you think about structure of both of them and why there 
 is one over the other?


They're the same documentation. IIRC, dlang.org/library/ was put 
together as a test of a different layout that was intended to 
replace the documentation at dlang.org/phobos. I don't remember 
who did it, or why the switch never happened.
Feb 21 2022
parent reply partypooper <pythonproof gmail.com> writes:
On Monday, 21 February 2022 at 11:58:08 UTC, Mike Parker wrote:


 They're the same documentation.


Yes, I know.


 I don't remember who did it, or why the switch never happened.


How long ago this switch was planned?
For me in current state api library > language reference.
Feb 21 2022
parent reply Mike Parker <aldacron gmail.com> writes:
On Monday, 21 February 2022 at 13:14:48 UTC, partypooper wrote:

 On Monday, 21 February 2022 at 11:58:08 UTC, Mike Parker wrote:


 They're the same documentation.


 Yes, I know.


 I don't remember who did it, or why the switch never happened.


 How long ago this switch was planned?


I don't know that a switch was ever planned, per se. Someone in 
the community got the ball rolling. I don't know anything about 
the details.


 For me in current state api library > language reference.


The documentation at dlang.org/phobos *is* the API library. The 
language reference is at dlang.org/spec.

Several people prefer Adam's version of the API docs that he 
linked above.
Feb 21 2022
parent partypooper <pythonproof gmail.com> writes:
On Monday, 21 February 2022 at 13:34:09 UTC, Mike Parker wrote:


 The documentation at dlang.org/phobos *is* the API library. The 
 language reference is at dlang.org/spec.


Oh, yes, not language, but library reference, my mistake. And 
yes, i understand that it is the same thing, just calling them by 
this titles that they have at this pages.
Feb 21 2022
prev sibling parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Monday, 21 February 2022 at 11:33:55 UTC, partypooper wrote:

 Personally currently in a stage of learning D I have found that 
 [API Documentation](https://dlang.org/library/) is much more 
 approachable and better structured than [Library 
 Reference](https://dlang.org/phobos/index.html)


If you want to see something significantly better than either, 
feast your eyes upon

http://dpldocs.info/std
Feb 21 2022
next sibling parent reply partypooper <pythonproof gmail.com> writes:
On Monday, 21 February 2022 at 13:16:39 UTC, Adam D Ruppe wrote:

 On Monday, 21 February 2022 at 11:33:55 UTC, partypooper wrote:

 Personally currently in a stage of learning D I have found 
 that [API Documentation](https://dlang.org/library/) is much 
 more approachable and better structured than [Library 
 Reference](https://dlang.org/phobos/index.html)


 If you want to see something significantly better than either, 
 feast your eyes upon

 http://dpldocs.info/std


Hell, Adam!
If I'm not mistaken it's your site (have seen it already). Good 
work, but I wouldn't call it significantly better than Api 
Library. Besides amazing source preview (better then redirect to 
github), that has helpful sidebar - it's almost the same as Api 
Library. Search on Api Library maybe not so comprehensive, but 
faster - because you get results without redirecting to another 
page. Do I miss something else? And there is some questionable 
design, but it is understandable if you are not web developer.
Feb 21 2022
parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Monday, 21 February 2022 at 13:48:07 UTC, partypooper wrote:

 it's almost the same as Api Library


yeah, they're generated from the same source.


 And there is some questionable design, but it is understandable 
 if you are not web developer.


Can you be more specific on this? Actually a lot of it came from 
new user a/b testing, but it still limited by me coming up with 
the options lol.
Feb 21 2022
parent partypooper <pythonproof gmail.com> writes:
On Monday, 21 February 2022 at 13:57:49 UTC, Adam D Ruppe wrote:

 On Monday, 21 February 2022 at 13:48:07 UTC, partypooper wrote:

 it's almost the same as Api Library


 yeah, they're generated from the same source.


 And there is some questionable design, but it is 
 understandable if you are not web developer.


 Can you be more specific on this? Actually a lot of it came 
 from new user a/b testing, but it still limited by me coming up 
 with the options lol.


There is no return to something like homepage button. Currently 
homepage is the same searchbar, but it would be cool to show at 
least standard library links here for easily approachable 
standard libraries without search. Because new D programmer as 
myself, I'm not always know what term to search exactly.

Not sure if it is a bug or what, but I can't find anything in 
phobos/core, phobos/dmd etc.

Sidebar of the source previewer looks weird (like overlapping 
scrollbars etc).
Anyway really good job, from now on I will use it instead of Api 
Library (only except for core library until it fixed).
Feb 21 2022
prev sibling parent Nick Treleaven <nick geany.org> writes:
On Monday, 21 February 2022 at 13:16:39 UTC, Adam D Ruppe wrote:

 http://dpldocs.info/std


I like the search results.

On Android mobile (portrait), the examples scroll horizontally 
but the function signature box doesn't.

I don't like not being able to see all the overload signatures at 
once. There's an ellipsis for a collapsed one that hides some 
parameters.

Personally I'm not keen on putting even each template parameter 
on its own line, often they're v short, T, U. I understand for 
function runtime parameters this can improve readability.

I tend to be less interested in constraints than arguments, yet 
the Phobos constraints often take up more lines than the 
parameters.
Feb 21 2022