On Mon, 29 Dec 2014 15:49:10 -0800 Walter Bright via Digitalmars-d <digitalmars-d@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.
signature.asc
Description: PGP signature