Re: Doc strings for complex cases?

[Matching Socks]

You can also put a docstring in a ns form to give context.

I don't think you need anything done to Clojure itself.  Or more 
specifically, you need not be limited by whatever Clojure has done with 
docstrings.  Nor will you need to modify defn.  You can attach any metadata 
you like, to the vars in your program.  Then your documentation report 
generator can use the metadata you attached.  (You wouldn't generate 
documentation directly from the source code text, of course.)  Since 
metadata is data structures, not just strings, the sky is the limit. 

By the way, there has also been discussion of best or expected use of the 
:arglists metadata.  Sometimes the arities you want to express in 
documentation differ from actual implementation, such as [& xs].  So 
probably you will not want a very rigid correspondence between your 
per-arity docstrings and the arities the compiler is aware of.

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Tim]

I think I have about two cases where multiple arity doc-strings would useful 
and for that I could just go without, but defmethods are more of a problem for 
me. I find defmethods can have greater contextual differences to the point I 
have been placing comments inline (;commented out lines) which I don't care for 
because you can't do standard lookups and inline comments just get in the way 
making the code harder to read. I'm not sure how changes could work from a 
lookup perspective, but that's where my pain is. And also, last week, I spent a 
good amount of time revisting some older code trying figure out what was going 
on, but alas I had only put a high level description in for the defmulti. 

Anyways, it's all good. I've been revisiting editors and tooling and I just 
think that's the best use of my time.
Cheers,
Tim 

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Didier]

What's the point of doc strings per arity? Wouldn't (doc fn) just 
concatenate them all back into one anyways? Or would you extend it to take 
an arity argument?

I think it seems to make sense to add them like that, but usability wise, 
when would you be looking at the doc of a single arity by itself? How would 
that work?

On Thursday, 9 November 2017 13:06:20 UTC-8, John Newman wrote:
>
> Way back when - when Rich was fielding suggestions for how to do doc 
> strings - I made the offhand comment that every arity could have it's own 
> doc string.
>
> He didn't like the idea back then. Doubtful he will now. I'm glad he went 
> the route he did.
>
> I believe the discussion took place on this mail list.
>
> On Nov 9, 2017 3:53 PM, "Mikhail Gusarov"  > wrote:
>
>> Hello.
>>
>> > Should any breaking changes occur in Clojure core,
>>
>> Why should they?
>>
>> Regards,
>> Mikhail.
>>
>> --
>> 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.
>>
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[John Newman]

Way back when - when Rich was fielding suggestions for how to do doc
strings - I made the offhand comment that every arity could have it's own
doc string.

He didn't like the idea back then. Doubtful he will now. I'm glad he went
the route he did.

I believe the discussion took place on this mail list.

On Nov 9, 2017 3:53 PM, "Mikhail Gusarov"  wrote:

> Hello.
>
> > Should any breaking changes occur in Clojure core,
>
> Why should they?
>
> Regards,
> Mikhail.
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Mikhail Gusarov]

Hello.

> Should any breaking changes occur in Clojure core,

Why should they?

Regards,
Mikhail.

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Tim]

Thanks for the suggestion(s), but I don't like the idea of writing custom code 
to implement better doc strings. Should any breaking changes occur in Clojure 
core, then I too could be forced to make changes and deal with broken code 
everywhere. If there was more community interest and the Clojure team 
implemented it then I'd be good because I know it would be maintained, but it 
doesn't seem like this is the case. So if it requires some custom work then I 
think I'd much rather do it at the tooling level as a plug-in to an editor. Ie, 
pull doc strings out all together and have them linked to and stored 
elsewhere... Maybe just store a db id in the doc string and go from there. I'll 
need to mull it over ;)

Thanks,
tim

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[lawrence . krubner]

I'm curious if it would be enough to write a macro that replaces defn in 
your code? The macro would secretly generate a different function for every 
arity, and therefore it could have a different doc-string for every arity, 
but it wouldn't have to appear that way in your code. Is that enough, or do 
you need something more fundamental? If so, can you say why? 

Seems like you could almost certainly do this for defmulti?


On Sunday, November 5, 2017 at 7:59:02 AM UTC-5, Tim wrote:
>
> I'm seeing a need to assign a doc string per arity case for defn and also 
> for each defmethod as opposed to storing it all in defmulti. Any solutions 
> or plans for this? 
> Tim

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Stuart Halloway]

Hi Tim,

You suggested a great reason yourself: "peoples approach to doc strings are
as varied as people are". To the extent that is true, someone would need to
propose a design considerate of that variety of needs (and tradeoffs!).
Without such planning, Clojure would evolve as a semi-random-walk of
itch-scratching. I have worked with tools that evolve this way and I am
thrilled that Clojure isn't one.

That said, Clojure is flexible enough that you could experiment with this
idea on your own and create a proof-of-concept requiring no change to core.
I am pretty sure you will encounter problems along the way. :-)

Cheers,
Stu



On Sun, Nov 5, 2017 at 10:24 AM, Tim  wrote:

> I expected a code smell response, but I simply don't agree with that. I
> believe peoples approach to doc strings are as varied as people are. I tend
> to be specific and want to add more context (do not read 'more content') in
> my doc string(s) than others might, but at the same time it's not like
> there's a shortage of poorly documented code in the world. So maybe we
> should consider other people's approach too. A simple solution might be to
> put the doc-string before the name:
>
> i.e. Instead of:
>
> defmulti the-name multi-fn
>
> use:
>
> defmulti "brevity matters in a doc-string" the-name multi-fn
>
> Or
>
> (defn
> "doc-string"
> ([x]...)
> "doc-string"
> ([x y] ...))
>
> Or is there a reason not to consider adding this?
>
> Cheers,
> Tim
>
>
>
>
>
>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Tim]

I expected a code smell response, but I simply don't agree with that. I believe 
peoples approach to doc strings are as varied as people are. I tend to be 
specific and want to add more context (do not read 'more content') in my doc 
string(s) than others might, but at the same time it's not like there's a 
shortage of poorly documented code in the world. So maybe we should consider 
other people's approach too. A simple solution might be to put the doc-string 
before the name:

i.e. Instead of:

defmulti the-name multi-fn

use:

defmulti "brevity matters in a doc-string" the-name multi-fn

Or

(defn 
"doc-string"
([x]...)
"doc-string"
([x y] ...))

Or is there a reason not to consider adding this?

Cheers,
Tim







-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Doc strings for complex cases?

[Mark Nutter]

That actually sounds like a kind of code smell to me. If your different
arities/defmethods are doing such disparate things that you can't easily
describe them in a single docstring, it's worth asking whether they need to
be separate functions.

On Sun, Nov 5, 2017 at 7:59 AM, Tim  wrote:

> I'm seeing a need to assign a doc string per arity case for defn and also
> for each defmethod as opposed to storing it all in defmulti. Any solutions
> or plans for this?
> Tim
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@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+unsubscr...@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+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.