Clojure docstring style

[cskksc]

Hello,

We are working on a new feature in CIDER which would parse a docstring and create hyperlinks that follow the functions/vars/interop-forms mentioned there.

It is very similar to the "See Also" links shown by ClojureDocs. Right now, we are using backticks to identify the reference forms and create links.

So a function like;

(defn test-mde

  "Does something with `user-ns/user-fn`.

   Also see: `clojure.core/map`, `clojure.core/reduce`, `defn`"

  []

  (+ 1 1))

would create hyperlinks for map, reduce, defn and user-ns/user-fn forms.

What style do you tend to use in such docstrings ?

It would help us figure out whether to continue with the backticks or do something else, like adding a configuration variable for this.

Thanks,

Chaitanya

[James Reeves]

If the docstrings are written in markdown, this would conflict as something in backticks isn't necessarily a var name.

In Codox, I used the wiki-link style: [[clojure.core/map]].

- James

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Christopher Small]

Seems like this shouldn't be a problem as long as you only try to render a link if there's actually such a var. This might be a little messier, but would make things (overall) nicer (I think) because you wouldn't have to think about a separate bit of syntax. The rendering would just happen differently depending on whether or not there was something to link to. I already do markdown in most of my docstrings anyway, and I'd prefer not having to rewrite a bunch of docstrings to take advantage of such a feature; I'm sure there are others with me as well :-)

This arguably violates least-surprise / separation of concerns, but in my opinion not so significantly that the costs outweigh the benefits (again, as long as you only tried to link if you knew it was a var).

My 2 cents...

Chris

[James Reeves]

On 16 May 2016 at 00:57, Christopher Small <metas...@gmail.com> wrote:

Seems like this shouldn't be a problem as long as you only try to render a link if there's actually such a var.

You could have some text you wish to render as code, which doesn't relate to a var but by coincidence happens to have the same name. For instance, you might have a docstring that references the SQL `update` command, which has the same name as a function in clojure.core. To my mind it's better to be explicit about what you want to link.

- James

[Matching Socks]

Cider could be most helpful by linking all words that could possibly be linked.  Everyone uses clojure.core, after all.

Cider could be most elegant by not attempting these links at all.

Cider could be most Emacs-like by letting users override the symbol detector with an Elisp function.  (Then someone could come along with a plug-in to automate the selection of a Codox algorithm, a clojure.core strategy, etc., for each namespace.)

[Phillip Lord]

The problem is that the var might not be a var yet. You'd have to
re-render code after evaluation.

Phil

Christopher Small <metas...@gmail.com> writes:

> Seems like this shouldn't be a problem as long as you only try to render a
> link if there's actually such a var. This might be a little messier, but
> would make things (overall) nicer (I think) because you wouldn't have to
> think about a separate bit of syntax. The rendering would just happen
> differently depending on whether or not there was something to link to. I
> already do markdown in most of my docstrings anyway, and I'd prefer not
> having to rewrite a bunch of docstrings to take advantage of such a
> feature; I'm sure there are others with me as well :-)
>
> This arguably violates least-surprise / separation of concerns, but in my
> opinion not so significantly that the costs outweigh the benefits (again,
> as long as you only tried to link if you knew it was a var).
>
> My 2 cents...
>
> Chris
>
>
> On Sunday, May 15, 2016 at 2:03:02 PM UTC-7, James Reeves wrote:
>>
>> If the docstrings are written in markdown, this would conflict as
>> something in backticks isn't necessarily a var name.
>>
>> In Codox, I used the wiki-link style: [[clojure.core/map]].
>>
>> - James
>>

>> On 15 May 2016 at 18:40, cskksc <ckop...@gmail.com <javascript:>> wrote:
>>
>>> Hello,
>>> We are working on a new feature in CIDER which would parse a docstring
>>> and create hyperlinks that follow the functions/vars/interop-forms
>>> mentioned there.
>>> It is very similar to the "See Also" links shown by ClojureDocs

>>> <http://clojuredocs.org/>. Right now, we are using backticks to identify

[nare...@helpshift.com]

Is there a convention to be followed for referring the parameters of a function in the docstring, e.g. for emacs lisp we upcase the parameter name?

[Eli Naeher]

On Wed, Sep 21, 2016, at 06:36 AM, nare...@helpshift.com wrote:

Is there a convention to be followed for referring the parameters of a function in the docstring, e.g. for emacs lisp we upcase the parameter name?

Uppercase is (or was) also pretty standard style in Common Lisp. In Clojure there does not seem to be a standard. Bozhidar Batsov's Clojure Style guide is silent on this. Core Clojure docstrings do not seem to identify parameters in docstrings with any special style. Some people use Markdown-style backticks, but I'm not sure how widespread that usage is.

-Eli

[John Gabriele]

I believe the Style Guide only codifies established styles, and I don't think there is one for this.

I'd use a Pandoc-markdown definition list in your docstring. For example, for `(defn foo [num to from] ...)`:

~~~
`num`
  : the number of frobnicators

`to`
  : location it's going to

`from`
  : location it's coming from
~~~

I don't know if the markdown processor for codex supports this markup, but I think it's good and it's used by a few other markdowns besides Pandoc.

-- John

[John Gabriele]

Forgot to add that that's the markdown syntax for definition lists (the backticks are just to format the definition terms in monospace). And it degrades pretty nicely for any md processors that don't support that syntax.

[Narendra Joshi]

Backticks are turned into links in cider-doc so I do this only for other definitions. To refer to arguments in a batch, I use:

varname    - description

varname2  - description2

I am not using anything for inline references to function parameters. But it would have been great if there was a convention for this.

Best,

Narendra

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to

clojure+unsubscribe@googlegroups.com

For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---

You received this message because you are subscribed to a topic in the Google Groups "Clojure" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/clojure/b9NOo0hOT9g/unsubscribe.
To unsubscribe from this group and all its topics, send an email to clojure+unsubscribe@googlegroups.com.

[Leon Grapenthin]

Couldn"t you just do it like this?

1. Parse docstring into symbols

2. If symbol is defined in the current ns, hyperlink

3. If symbol is namespace-qualified, hyperlink

4. If symbol is name of an arg, hyperlink

This should leave very few false positives where an english word is the name of a var in your ns or of an fn-arg which I'd expect to be very rare - would be more than good enough for me.

Docstring syntax for IDEs and generators is something I never liked. They are strings, not data, by definition. There are already too many conventions for different tools so a a common convention is not likely to happen so this would fragment how docstrings look like even more.