Glossarist gem is very difficult to use

[ronaldtse]

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]

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]

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

• Lock Glossarist to model V1 metanorma/metanorma-plugin-glossarist#22
• Malformed Asciimath equations  metanorma/stepmod-utils#191