search

noinia / hgeometry

HGeometry is a library for computing with geometric objects in Haskell. It defines basic geometric types and primitives, and it implements some geometric data structures and algorithms. The main two focusses are: (1) Strong type safety, and (2) implementations of geometric algorithms and data structures that have good asymptotic running time guarantees.
120 stars 40 forks source link

difficult to use without documentation - examples do not compile with hackage! #208

Open andrewufrank opened 1 year ago

andrewufrank commented 1 year ago

I tried to use this package as it seems to have a nice collection of geometric algorithms - but without documentation seems impossible.

I tried working with the examples - which usually helps - but, sadly, the example provided do not compile. The imports do not fit with the code in hackage (which wants Data.Geometry and not just Geometry) and the code does not accept the types Point 2 Int definition (btw, I understand what type level Nat should be but do not see how you use them here).

Please provide some simple examples to start with (e.g. define a couple of points and calculate distance between them) and make sure it compiles and runs with the code from hackage -- or add a warning to the READ.ME "no documentation and no usable example code provided!" so others do not waste time to guess how this could be used.

noinia commented 1 year ago

In the master branch here on github (yet unreleased on hackage) the modules were renamed; as you observed the modules which were named Data.Geometry.XYZ are now simply called Geometry.XYZ. So if you want to compile one of the examples from github using hgeometry-0.14 you'll have to rename the imports to 'Data.Geometry.XZY' again; for the rest the examples should mostly compile as is.

To use the 'Point 2 Int' part you'll likely need the DataKinds GHC language extention, and possibly others. See the 'Default-extentions' field in the cabal file for any other extensions you may need.

As for examples: I'm aware there are few examples available. Feel free to contribute some..... As for your specific question 'defining a couple of points and calculating the distance between them'. I would hope the type signature of Data.Geometry.Point.euclideanDist tells you everyting you need to know.....

andrewufrank commented 1 year ago

Thank you for your answer. The renaming of the modules I figured out, but the data kinds extension is newer than when I experimented with type level natural numbers, so I did not think of it. The examples did not compile when copied in a new project; they perhaps compile when copied the whole project.

i gave up after wasting a number of hours, unhappy because (a) waste of time with no gain, (b) I had the feeling this would be a very usable package (to which I would perhaps contribute later) and frustrated about the lack of the most minimally required documentation (for example, if you use language extension, put them in the code not the cabal file, which is not copied if one wants to use a package in another project with its own cabal file...).

The project looks promising, but if the first attempt is as frustrating as this one, you will not find many users, contributors.