Worst Phobos documentation evar!

[ketmar via Digitalmars-d]

On Wed, 31 Dec 2014 15:52:45 -0800
Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:

> The point is, you do not have to use the macros if Ddoc if you don't want to.
the point is that i can't have documentation that both readable without
preprocessing and generates good standalone files. i have to choose one
of that. ah, and then i'll stick to my own documenting rules, 'cause i
will not use Ddoc to generate anything anyway.

it's not that hard to extend human-readable markup language to allow
some D-specific features. i already wrote that this can be any
language, not necessary markdown. like this, for example:

=|Function Name|Description|=

 |`boyerMooreFinder`
   | `find("hello world", boyerMooreFinder("or"))`
     returns `"orld"` using the (Byer-Moore algorithm)[1].

 |`count`
   | Counts elements that are equal to a specified value or
     satisfy a predicate.
     `count([1, 2, 1], 1))` returns `2` and
     `count!"a < 0"([1, -3, 0])` returns `1`.

[1] https://some-long-link-with-alot-of-args


now compare with this:

$(TR $(TH Function Name) $(TH Description)
)
$(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find("hello
world", boyerMooreFinder("or"))) returns $(D "orld") using the $(LUCKY
Boyer-Moore _algorithm).)
)
$(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal
to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1))
returns $(D 2) and $(D count!"a < 0"([1, -3, 0])) returns $(D 1).)
)

it doesn't matter how much efforts you will put into latest, it will
look like linenoise anyway.

yes, documentation processor should be able to see that
`boyerMooreFinder` and `count` are declared in the respective module
and turn that to internal links. i can't see why i should do the work
that computer can do for me.

i devised this sample without deep design, of course, yet it's already
human-readable and can be used to generate any kind of table.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20150101/31dc5e8b/attachment-0001.sig>