Quickdoc text readability.

[aadrian]

Please improve the readability of the QuickDoc text (Ctrl+Q): there seems to be only a single font and no formatting for the entire text: so no monospace formatting for the code snippets, that are mixed with normal English text :(.

This makes reduces the usefulness of QuickDocs greatly: way below of what users are used to with JavaDocs.

Thanks in advance.

[pazustep]

Funny, it's the other way around for me: docs are always displayed in a monospaced font:

[cursive-ide]

Hmm, interesting - I'm on a mac and the font is monospaced (in fact the text is HTML and I wrap it all in a <pre>).

[cursive-ide]

BTW which platform are you on?

[aadrian]

Compared to Javadoc, not having a visual distinction between code and text is a big step backwards IMO.

In my example there's also inline code that is not at all distinguishable from text :(.

BTW which platform are you on?

Win8 + IU 13.01

[cursive-ide]

Unfortunately that's something that's unlikely to ever be fixed. This is really a problem with Clojure - docstrings are just text, whereas Javadoc is HTML. I'd have to parse out parts of the text that look like code, and there's really no reliable way to do that.

[pazustep]

By the way, many clojure projects assume docstrings use markdown syntax. This was probably pioneered by marginalia. Maybe cursive could offer an option to render docstrings using markdown.

[aadrian]

Unfortunately that's something that's unlikely to ever be fixed. This is really a problem with Clojure ...

That's a pity and a big step backwards :(.

HTML is not fun to write in JavaDocs but is very helpful when reading.

Maybe cursive could offer an option to render docstrings using markdown.

+1

[cursive-ide]

Sure, that would be quite easy. But that still won't address the fact that most code in docstrings is not marked up. It would have to be switchable per docstring since Markdown could render some existing docstrings incorrectly.

[aadrian]

Sure, that would be quite easy.

Nice. The question is if it is realistic at all to hope that it will be adopted for the core stuff, since that's what most users will want to read.

But that still won't address the fact that most code in docstrings is not marked up. It would have to be switchable per docstring since Markdown could render some existing docstrings incorrectly.

What about just whitelisting where it's already known that it is docstrings? E.g. based on some public repo on github so that people can easily contribute to this "whitelist".

And also default on for user code, so that users are encouraged to use it?

[werne]

+1

[hansgru]

+1

The readability of docs for windows is just plain horrible.

[cursive-ide]

@hansgru Are you talking about the font, or the lack of markdown?

[hansgru]

I'm not sure if this is a font problem or a Cursive/Clojure problem, but the readability is quite bad. Of course, "markdown" would increase greatly, but I suppose that's quite a huge feature request.

The formatting of the list of possible parameters is also very user unfriendly: basically I need to use (doc something) command all the time and that's very inefficient compared to quick CTRL+Q everywhere.

[cursive-ide]

I just tried this:

(doc clojure.core/defn)
-------------------------
clojure.core/defn
([name doc-string? attr-map? [params*] prepost-map? body] [name doc-string? attr-map? ([params*] prepost-map? body) + attr-map?])
Macro
  Same as (def name (fn [params* ] exprs*)) or (def
    name (fn ([params* ] exprs*)+)) with any doc-string or attrs added
    to the var metadata. prepost-map defines a map with optional keys
    :pre and :post that contain collections of pre or post conditions.
=> nil

I don't understand what is more user-friendly about the doc output than the popup version. Even with bad fonts, it's easier to read. What is so user-unfriendly about the param list?

[hansgru]

See the difference above.

The CTRL+Q version is just confusing (even if it tries to be better). In this case, it would be helpful if:

• the FQN (in the first line in the screenshot) would be with a Bolder font. (macro) would be an icon or colored differently, or it wouldn't be present on the first line at all.
• It's nice that the parameters are shown with the call, but in this case the FQN creates confusion. The short name + syntax highlighting would solve the problem for this second line in the screenshot.

[hansgru]

or this:

[cursive-ide]

Thanks for the details. The FQN on the first line is actually wrapped in a bold tag, and appears bold to me on OS X. I'm not sure why it doesn't on Windows. I can put the "macro" on the next line to match doc, and I'll look to see why the fn output is different to its output for doc.

[cursive-ide]

I thought something about your output looked strange, so I tried it out. At least part of the problem is that there's a difference between how the doc is displayed in the editor and how it's displayed in the REPL: Editor: REPL: Editor: REPL: The FQN is actually bold in all of them. Looking at your screenshot, the FQN does look slightly bold compared to the rest of the text, but it's very slight - that looks like a font issue.

[hansgru]

The FQN is actually bold in all of them. Looking at your screenshot, the FQN does look slightly bold compared to the rest of the text, but it's very slight - that looks like a font issue.

Thanks for analyzing this problem.

I can see this on all Windows machines I have access to :(. ( Not using the Mac for coding because of it's horrible keyboard layout)

It is very well possible that this is an IntelliJ bug (have no idea), nevertheless the readability and the efficiency of the quick doc is very important IMO.