Glossarist gem is very difficult to use

ronaldtse commented 10 months ago

Today I was trying to create a Concept object.

And imagine the frustration with creating such an object without any documentation. That's right -- the Glossarist gem has no documentation, and the specs do not even show any complete example.

I had the hardest time figuring out that this line doesn't work.

Glossarist::Concept.new(designations: [{designation: "xyz", type: "expression", normative_status: "preferred"}])
# => works

The reason is the designation object must be using "string encoded" hashes, not symbol ones.

Glossarist::Concept.new(designations: [{"designation" => "xyz", "type" => "expression", "normative_status"
 => "preferred"}])
# => works

This is because of this code:

module Glossarist
  module Designation
    class Base < Model
    # ...
      def self.from_h(hash)
        type = hash["type"]

        if type.nil? || /\w/ !~ type
          raise ArgumentError, "designation type is missing"
        end

This is not acceptable...

ronaldtse commented 10 months ago

This is the problem of a gem that is only being used by one developer -- only the same developer is familiar with the oddities of the gem, but no one knows how it actually works. All typical expectations, and the fear of other developers looking at the same code, are out the window.

This is not right. When we create a gem, it is expected to be USED BY OTHERs. This means we need proper code documentation, i.e. RDocs. At a minimum, provide a README on how to use the gem. Right now, none of that exists.

HassanAkbar commented 10 months ago

@ronaldtse I'll start working on the documentation right after the following tasks are finalized

glossarist / glossarist-ruby

Glossarist gem is very difficult to use #81