www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Making Phobos's documentation better

reply Seb <seb wilzba.ch> writes:
JackStouffer is doing a lot of work lately on this check and I 
think we can help him too:

https://github.com/dlang/phobos/projects/1

So if you have 15 spare minutes why not help out and make 
Phobos's documentation better?
After all, almost everyone in the State of D survey agreed that 
the documentation isn't superb yet.

How can I help?
---------------

1) If you don't have Phobos setup. Fork & clone the four main 
repos

---
mkdir ~/dlang && cd dlang
git clone https://github.com/<username>/dmd
git clone https://github.com/<username>/druntime
git clone https://github.com/<username>/phobos
git clone https://github.com/<username>/tools
cd phobos
make -f posix.mak
---

2) Pick a module and remove it from the has_public_example 
blacklist in .dscanner.ini

3) Run make -f posix.mak dscanner

4) Add unittest

5) Run the tests with either

- make -f std/mymodule.test (this rebuilds Phobos before running 
the tests)
- ~/dlang/dmd/generated/linux/release/64/dmd -unittest -main -i 
-run std/mymodule.d (faster as it doesn't rebuild Phobos)
- make -f std/mymodule.publictests (this extracts the public 
tests into a separate file to prevent any private access problems)

6) Submit a PR

7) GOTO 2 (or celebrate)


There are also a few other blacklists here too:

https://github.com/dlang/phobos/projects
Mar 20 2018
parent reply WebFreak001 <d.forum webfreak.org> writes:
On Tuesday, 20 March 2018 at 15:19:14 UTC, Seb wrote:

 JackStouffer is doing a lot of work lately on this check and I 
 think we can help him too:

 [...]


hm but adding examples to some symbols just doesn't make sense, 
for example `translate` in std.string: `translate` has no 
example, but the symbol directly below it (`makeTrans`) has an 
example documenting both, why would you add an example just for 
`translate` here?
Mar 20 2018
parent Seb <seb wilzba.ch> writes:
On Tuesday, 20 March 2018 at 16:13:23 UTC, WebFreak001 wrote:

 On Tuesday, 20 March 2018 at 15:19:14 UTC, Seb wrote:

 JackStouffer is doing a lot of work lately on this check and I 
 think we can help him too:

 [...]


 hm but adding examples to some symbols just doesn't make sense, 
 for example `translate` in std.string: `translate` has no 
 example, but the symbol directly below it (`makeTrans`) has an 
 example documenting both, why would you add an example just for 
 `translate` here?


tl;dr: because of e.g. single page per symbol documentation like 
ddox (or adrdox) and consistency/automated checking.
Example: https://dlang.org/library/std/string/translate.html

Duplication can be avoided with `/// ditto`.

---

translate is a bad example, because it's an old symbol from D1 
times and I think it would never have been added to Phobos 
nowadays as it heavily depends on the GC by design and it's 
super-hard to use it in ` nogc` (that applies for most of 
std.string FWIW).

Also it has six overloads doing almost the same thing, which 
makes it rather hard to grasp for newcomers.
A modern translate would probably be more generic, e.g. use an 
OutputRange instead of a buffer, allow any kind of translation 
table to me passed and probably not couple removal into this 
function.

makeTrans is a similar legacy symbols and would nowadays accept 
an Allocator optionally, probably return something hashmap-like 
(instead of a GC-allocated string) and maybe even return 
something RefCounted.

Also since 2.079, there's substitute which can handle many cases 
of translate with one API:

"foobar".substitute("foo", "föö");
Mar 20 2018