Splitting 'lib_classes.i' Into Sub-Modules

[tajmone]

• [x] Split lib_classes.i into:
  • [x] lib_actors.i
  • [x] lib_clothing.i
  • [x] lib_liquid.i
• [x] Update the following docs, accordingly:
  • [x] READMEs
  • [x] CHANGELOG
  • [x] StdLib Manual:
    • [x] Ch 1. Who Needs a Library? — list of all library modules.
    • [x] StdLibMan-inc_attributes.adoc — link attributes to StdLib sources.
    • [x] Any references to lib_classes.i in the context of:
      • [x] Actors.
      • [x] Clothing.
      • [x] Liquid.

---

@AnssiR66, I personally find the lib_classes.i module to be too huge to handle — it currently stands at 2352 lines of code in total. When I need to work on verbs which are defined on multiple classes, it's not easy to juggle this huge single-source, and having to jump up and down the code. (Sure, modern editors allow multiple views on a same source, but when it comes to S&R operations, split files are safer).

I was thinking that we could split it up into additional modules, at least partly, moving out the classes that are really bulky.

Since end users only need to IMPORT the main StdLib module, they shouldn't care less how many modules there are in the Library (especially if they keep its sources in a subfolder, separate from their adventure sources) — unless they wish to study or edit the Library sources, in which case modularity makes the task easier.

I've done a quick and rough estimate of how many lines of code are taken by each class definition, and these are the results in total lines of codes per class

(The Bar Chart was created using Meta-Chart, a free online service.)

I think we should probably move to independent modules at least ACTORS, CLOTHING and LIQUID. We could name the new modules:

• lib_classes_actors.i
• lib_classes_clothing.i
• lib_classes_liquid.i

but it might be too verbose and could opt for:

• lib_actors.i
• lib_clothing.i
• lib_liquid.i

instead, which is briefer — and also more in line with lib_locations.i, which is class-related module after all.

Moving these classes to independent modules would relief lib_classes.i of 1334 lines of code, reducing its size to roughly 1018 lines — less than half its original size! This should make it more manageable to work with.

What are your thoughts on this?

[AnssiR66]

Yes, this is a good idea and makes things easier to find. We can do these changes.

[tajmone]

Done! I've managed to split lib_classes.i, as mentioned above.

I've started to polish the comments to mirror the updated library structure, but there's still quite a lot to do in that respect — I just didn't want to pack too many changes into a single commit, and chose to postpone the task to later on.

Also, I've noticed that some code snippets should probably be moved from one module to the other — e.g. the default DESCRIPTION that handles scenery objects:

ADD TO EVERY OBJECT

  DESCRIPTION
    CHECK THIS IS NOT scenery
      ELSE SAY "".

END ADD.

which is currently in lib_classes.i, but should probably be moved to lib_definitions.i, since a scenery object is (no longer) an independent class, it's just an attribute (probably it was left there from the time when it used to be a class).

And other similar snippets that could be moved around to improve code consistency, and possibly avoid redundant ADD blocks.

---

Now that we've gained back so much space from the various library modules, we could use that space to improve comments documentation — also bearing in mind that with the next ALAN Beta we'll be benefiting from block comments, which will allow us to include:: documentation snippet from the library sources directly into the StdLib Manual, lifting from us the burden of having to maintain and update multiple documentation texts.

We might want to focus on the in-source documentation in view of the upcoming candidate release; for if we can't manage to come up with an up-to-date version of the Manual, end users will have to rely on the comments found in the library modules. There's already a lot of documentation and examples in the sources' comments, we just need to double check that none of it refers to obsolete library features, and flesh it out a bit more in various places (but often it's just a matter of fixing line-wrapping and indentations).

We could leave this Issue open for another while, to keep the discussion on the newly added modules alive (no reason to create a new Issue, really).