Worst Phobos documentation evar!

[ketmar via Digitalmars-d]

On Mon, 29 Dec 2014 15:49:10 -0800
Walter Bright via Digitalmars-d <digitalmars-d at puremagic.com> wrote:

> On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
> > Ddoc isn't too bad, but trying to document examples in dom.d turned into a mess
> > of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
> 
> I'd make a macro:
> 
>     XML=$(LT)$0/$(GT)
> 
> I use custom macros all the time in Ddoc. If you aren't, you're not doing it 
> right :-)
that's why ddoc is completely unusable either for reading "as is" or
for generating separate documentation.

i was very excited about built-in documentation generator in D, and now
i'm not using it at all. i rarely generating stand-alone docs, they are
just not handy for me. i prefer to read documentation right in the
source (yet i still want to have an option to generate stand-alone
files). did you tried to read Phobos documentation in Phobos sources?
those macros are pure visual noise. i don't mind if D will understand
one of the Markdown variants, or textile, or rss -- anything that is
READABLE without preprocessing, yet can be easily processed to another
format. i don't mind learning another markdown dialect if i can easily
read it without preprocessing.

that's why i'm not using doxygen too: it's noisy. seems that most
document generator authors are sure that only generated documentation
matters, so source documentation can be of any uglyness. yet if
documentation is hard to read without preprocessor, it is hard to write
it too! so people will tend to avoid writing it, and they will
especially avoid polishing it, 'cause it's write-only, contaminated and
hard to fix.

D documentation WILL be bad until ddoc will start to understand some
markdown-like mostly macro-free markup language.
-------------- 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/13e27460/attachment.sig>