Worst Phobos documentation evar!

[ketmar via Digitalmars-d]

On Mon, 29 Dec 2014 20:30:48 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d at puremagic.com>
wrote:

> On 12/29/14 6:49 PM, ketmar via Digitalmars-d wrote:
> > On Mon, 29 Dec 2014 18:43:56 -0800
> > Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:
> >
> >> On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
> >>> it's great that Ddoc is good for making books. but it's not so great
> >>> that it's bad for documenting source code.
> >>
> >> I also use it for all the documentation on the Digital Mars site, which include
> >> a lot of coding examples, the articles I wrote for Dr. Dobb's about code, all
> >> the documentation on walterbright.com, etc.
> >
> > yes, that's exactly why it's not so great for documenting source code.
> > you basically invented your own TeX, which has alot of features to
> > write stand-alone texts, but almost completely unreadable as a source
> > code documentation without preprocessor. Ddoc is just too powerful.
> 
> I use (La)TeX macros all the time, and although necessary they're beyond 
> awful. DDoc macros are a lot nicer and more consistent by comparison. 
> They are not, however, as powerful. -- Andrei

i don't want to say that Ddoc is better or worse than (La)TeX. the
problem is that it unreadable due to visual noise. my point is that
Ddoc documentation should be easily readable without preprocessing,
right in the source code.

markdown, textile, restructured... see the pattern? they all easily
readable by humans without preprocessing. Ddoc is not. it is painful to
read "rich" Ddoc comments AND it is painful to write 'em.

that's why Ddoc is "too powerful": it has great macro system which
gives Ddoc great power, but for the price. this price is "visual noise".

most people don't need DTP package in documentation, they need simple,
clean and human-readable syntax for WRITING that documentation in the
first place. Ddos is perfectly usable, but it's uncomfortable to write
nice documentation with it.

Ddoc is for writing *reference* *documentation*, not complete
documentation books. and it is simply too powerful for that. having
Ddoc is great, but it's oftenly overkill to use it. i believe that Ddoc
should be opt-in, and by default D should use one of the human-readable
text formatting languages with some D-specific extensions (like easy
cross-referencing, for example). most people will be OK with simple
language for documenting API and will resort to "real Ddoc" only when
they want to write something like wordy and detailed explanation of
internal algorithms and such.
-------------- 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/20141230/e34b4ea2/attachment.sig>