Do you think my interface is intuitive? If not, how can I improve?

[rozick1]

I am writing a library which which has an Entityspace. The Entityspace can contain different entities and these entities can be linked (as parent or a child).

I've written some code below and would like to know if I can make the interface more intuitive.

entlib::Entityspace test;

// add entities

entlib::EntityID father = test.addEntity("Father Ltd", entlib::EType::LTD); 
entlib::EntityID son = test.addEntity("Son LLP", entlib::EType::LLP); 
entlib::EntityID mother = test.addEntity("Mother Plc", entlib::EType::PLC); 

// register LinkTags
test.registerLinkTag("Ordinary");
test.registerLinkTag("Preference");
test.registerLinkTag("Other");

// make links
test.linkAsParent(father, 40, entlib::TagType("Ordinary"), son); // one way of adding a link

entlib::link newlnk = entlib::link{son,40,entlib::TagType("Ordinary"), entlib::RType::PARENT_OF}; // another way
test.addLink(father,newlnk);

[JLBorges]

Something like this may make the user code easier, more succinct:

entlib::Entityspace test;

// register three LinkTags with an initisalizer_list
test.registerLinkTags( { "Ordinary", "Preference", "Other" } );

// add entity
auto father = test.addEntity( "Father Ltd", entlib::EType::LTD); 

// add entity and automagically add the appropriate links too
auto son = test.addEntity( "Son LLP", entlib::EType::LLP, entlib::SON_OF(father,"Ordinary") ); 
auto mother = test.addEntity( "Mother Plc", entlib::EType::PLC, entlib::PARENT_OF(son,"Ordinary")); 

[dhayden]

What happens in entlib::TagType("Ordinary") if "Ordinary" hasn't been registered? Ideally your code should make errors like that difficult, if not impossible.

You could make entlib::EntityID a class and pass the TagType ID:

entlib::EntityID father = test.addEntity("Father Ltd", entlib::EType::LTD); 
entlib::EntityID son = test.addEntity("Son LLP", entlib::EType::LLP); 
entlib::EntityID mother = test.addEntity("Mother Plc", entlib::EType::PLC); 

// register LinkTags
test::TagID ordinary{test.registerLinkTag("Ordinary")};
test::TagID preference{test.registerLinkTag("Preference")};
test::TagID other{test.registerLinkTag("Other")};

// make links
son.linkAsParent(father, 40, ordinary);

entlib::link newlnk = entlib::link{son,40,ordinary, entlib::RType::PARENT_OF}; // another way
father.AddLink(newlnk);

In all cases, what is the "40" parameter?