On 2016-09-14 22:14, Andrei Alexandrescu wrote:

Why? -- Andrei

I've recently worked on a theme for Ddoc that will be used in TextMate. For convince I started by adding the CSS inline in the head tag. Turns out if you have CSS looking like this:

.foo {
  font-weight: bold;
  background-color: white;

Everything works perfectly fine. Then I added text color as well:

color: black;

Guess what happens? It cuts, it cuts everything after "color". The solution is to use a colon macro:

  COLON = :

color$(COLON) black;

It took me quite a while and a lot of frustration until I figured that out. But I guess that's an inherit problem with a macro system.

That is what I'm missing from Ddoc:

* Inline source code for each symbol [1]. The [1] example both has a button to show the source code inline and a direct link to GitHub

* Link to GitHub for each symbol [1] and for the whole module. The way it's done now with $(PHOBOSSRC std/net/_isemail.d) is not standardized and feels like a hack. Why slashes and why the underscore? If anything it should be the fully qualified name. Ideally it should be automatic, or a compiler recognized macro that inserts the link

* Ddoc should organize symbols by visibility [2]
* Ddoc should generate index table [3]
* Ddoc should organize a module by symbol category [4]
* Add a way to inherit documentation from the parent class [5]

* Ddoc should give a list of inherited members [6]. JavaDoc does this by default [7]

* Consistent way of cross-referencing. Ideally one would just pass the fully qualified name (or local name for symbols in the same module) to a compiler recognized macro and it would generate the appropriate links

* An index page with all symbols, including a filter [8]. This is super convenient when you know the symbol to use but you need to double check how it's used or the behavior. I use it almost every day with Ruby

All this should be done within Ddoc without the need for any post processing.

In general I feel that Ddoc is too much focused on a generic macro system instead of focusing on being a good tool for writing documentation for code.

[1] http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html#method-i-first

[2] https://issues.dlang.org/show_bug.cgi?id=11893
[3] https://issues.dlang.org/show_bug.cgi?id=11891
[4] https://issues.dlang.org/show_bug.cgi?id=11892
[5] https://issues.dlang.org/show_bug.cgi?id=10399
[6] https://issues.dlang.org/show_bug.cgi?id=7688

[7] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fjdt%2Fcore%2Fdom%2FSimpleName.html

[8] http://ruby-doc.org/core-2.3.1

/Jacob Carlborg

Reply via email to