On 09/15/2016 02:55 AM, Jacob Carlborg wrote:
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:

Macros:
  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.

Yah, this is terrible (it happens with http: all the time). We need to suppress the special meaning of ":" to only the cases when it's preceded by only one word and followed by a newline, e,g, "\ncolor:\n".

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

Can this be done by defining the expansion macros appropriately?

* 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?

Slashes are tolerable. The underscore I agree it's a quirk.

If anything
it should be the fully qualified name.

That'd be nice.

Ideally it should be automatic,
or a compiler recognized macro that inserts the link

Ironically the underscore is necessary because ddoc does too much automatically.

* 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.

I think we should start with a postprocessing-based approach and see what capabilities need to be added to obviate the need for postprocessing.

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.

That's a fair assessment, and an actionable one.


Andrei


Reply via email to