Please, put the to/fromList conversion cost more clearly

[Anton-Latukha]

Currently the main info is in fromList

dlist/Data/DList/Internal.hs

Lines 104 to 136 in 1793a5e

	{-|
	__@fromList xs@__ is a 'DList' representing the list __@xs@__.
	@fromList@ obeys the laws:
	@
	'toList' . __fromList__ = 'id'
	__fromList__ . 'toList' = 'id'
	@
	This function is implemented with '++'. Repeated uses of @fromList@ are just as
	inefficient as repeated uses of '++'. If you find yourself doing some form of
	the following (possibly indirectly), you may not be taking advantage of the
	'DList' representation and library:
	@
	__fromList__ . f . 'toList'
	@
	More likely, you will convert from a list, perform some operation on the
	'DList', and convert back to a list:
	@
	'toList' . g . __fromList__
	@
	-}
	{- ORMOLU_ENABLE -}
	{-# INLINE fromList #-}
	fromList :: [a] -> DList a
	fromList = UnsafeDList . (++)

This paragraph:

If you find yourself doing some form of the following you may not be taking advantage of the 'DList' representation and library:

fromList . f . toList

More likely, you will convert from a list, perform some operation on the 'DList', and convert back to a list: 

toList . g . fromList 

fromList :: [a] -> DList a 
fromList = UnsafeDList . (++)

"If you find yourself doing some form of the following" implies that everything that follows - is counterproductive. & logically both fromList . f . toList & toList . g . fromList for simple things are counterproductive. & "following" statement opens - and never stops, never says where examples & "following" stops & it does not even have a . at the end of sentences - so that means "everything that follows".

"If you find yourself doing some form of the following ... More likely, you will convert ..." - what does that mean = it is an ad hominem probabilistic characteristic, not a statement or explanation, moreover it applies things to me and not to a library or compiler. It not forgot to mention me in the docs, but forgot to mention if the way discussed there is recommended, or as "following" implies - just as counterproductive. Dwelling on ad hominems you we so much - to show a trend in the documentation of use those easy escape words as diversions, instead of the description of the process & objects involved. If to just remove personal directioning from docs - they suddenly both shorter & understandable.
As:

'fromList . f . toList' - does not be take advantage of the 'DList'.
'toList . g . fromList' - takes advantage of the 'DList' optimized operations.

suddenly text 2 times shorter & clear.

Moreover - that paragraph can be removed entirely as tautology - of course doing operations with other type & functions - is not using DList.

Having O notation & stating from/toList costs is enough to infer where it is useful.

I vaguely remember reading about DList directions of conversion, but it was years ago & do not remember if anisotropy (directional properties) came out being imaginary or real, if it is stated clearly in the doc - users would not need to remember it from years ago & would not get puzzled.

[spl]

You elided the important part: “Repeated uses of fromList are just as inefficient as repeated uses of ++.” The rest is just elaboration on that statement with explicit mention of the direction of conversion and written in casual language that is meant to gently help guide the reader.

I'm not sure what you mean by “ad hominem” here, but I don't think I'm guilty of committing an informal logical fallacy.

There may be room for improvement on the documentation, but it seems you figured out what it meant, which is the important thing.

Thanks for your interest! But I think it's good enough for now.

[Anton-Latukha]

ad hominem literally is (directing) "to the person". I just underline that when people describe processes, for example in compiler garbage collection - they somehow drag me into actively doing byte block manipulation & I do not know where the compiler went in that process. I do collect garbage in real life, but I never collected garbage in a compiler garbage collector. It is if someone (something) else did all the work & I somehow claim that I did it, when I was never involved in that process.

For me - using informal you & we informal language in documentation - actually complicates the understanding of the documentation & process strongly. Because there is no longer lexer, syntactic analyzer, Haskell Core analysis & optimizer, compiler, STGM, type checker, compiler type inference, runtime inference - of course, all those parts can be replaced by "we do", why we would need to use a technical vocabulary in description of technical processes. you/we ad hominem use diverts the description from what part of the system does what, so in sum when we or you is used as a replacement for 1 (if that 1 can not be inferred back) or more subsystems in the process ... that description actually becomes useless quickly, as person now only vaguely can understand what actions are taking place but frequently nothing else, does not understand what it is, how it works & what parts are there & how they go together, now since reader had no information provided on what parts do what, the reader after reading informal official documentation - needs to go read the side-car 3rd-party articles that explain the topic in detail & hope those article authors understand & give everything right & then go and read the source code, which shows that we/you use for technical processes defits the purpose of having official documentation.

Sometimes after we/you it is still possible to infer back what was meant to be said, but frequently it becomes a probabilistic superset of variants "what that could meant" which is trying in the context of lack of information given to infer possible combinatorics on what object names were erased while frequently not even knowing what are the terms that were erased, so person needs to go inference one level higher - & infer what terms could be used in the doc & then infer through we/you typed holes what substitution of the object should be used & how it changes inference.

Sometimes the side-effect of informal we/you replacements, when authors care to make approachable documentation - authors start to perpetuate the problem by increasing the size of informal descriptions & doing rondos on the theme, so to cover enough term holes from different angles so reader term inference can kick-in, which creates a problem of docs/tutorial being too big to be read/understood in a day & so now they driven users & themselves into tldr.

[Anton-Latukha]

I do mention, that theme does not involve the value of DList being a beautiful data type solution to [] problem.

But I do think that lack of documentation on DList (& obscurity of laziness leverage process) contributed to that people do not understand really how DList works & so where it really shines to use it, which impacted the adoption of it. I found http://h2.jaguarpaw.co.uk/posts/demystifying-dlist/ being most descriptive. Trying to help with adoption through: #102, as there people would see that DList is worth being used for {snoc,cons,append} and others. Numbers for DList performance actually surprised me. But to have adoption library needs according docs on how & why it works so well.