Update NASDF to 1.3.

[aartaka]

There's a lot of errors raised by undocumented exports test. @Ambrevar, want me to fix these?

[Ambrevar]

Something is off with the compilation test. For instance read-handler has a documentation string. My guess is that slot documentation is not found.

If you know which class the slot belongs to, then it's easy to check for documentation:

(getf (mopu:slot-properties 'CLASS-NAME 'SLOT-NAME) :documentation)

However, how can we find the associated class(es)?

[aartaka]

Something is off with the compilation test. For instance read-handler has a documentation string. My guess is that slot documentation is not found.

Yes, slot documentation has no standard way for documentation fetching (see standard page for documentation). We can go through all the classes in the package and look at their slots documentation via MOP. However,

• This solution requires bringing MOP into Nfiles,
• And NASDF shouldn't have any dependencies, AFAIK.

So using MOP is not an option.

That's why there are two exceptional cases to the documentation test, both with respective ways to handle them:

• A sole defmethod: auto-generated generic function has no documentation, so we have to use explicit defgeneric, which is a good tone anyway.
• Slot documentation: impossible to fetch portably, so just add slot name to the :undocumented-symbols-to-ignore, as in (example from ndebug, where exported slots restarts, condition-itself, and stack have no documentation):

  (defsystem "ndebug/tests/compilation"
  :defsystem-depends-on ("nasdf")
  :class :nasdf-compilation-test-system
  :undocumented-symbols-to-ignore (:restarts :condition-itself :stack)
  :depends-on ("ndebug")
  :packages (:ndebug))

[Ambrevar]

Maybe better: If symbol is not fbound, bound, a class, etc. (see other compilation test), then do not check the doc.

[aartaka]

Maybe better: If symbol is not fbound, bound, a class, etc. (see other compilation test), then do not check the doc.

Most of the exported slots also have accessors, so that doesn't work as a heuristic. And then, if the symbol is not bound as per ubound-exports, then it's a whole different class of errors :D

[Ambrevar]

Then I don't find the documentation check very satisfactory, since maintaining this list of symbols to ignore could itself lead to mistakes.

[aartaka]

Then I don't find the documentation check very satisfactory, since maintaining this list of symbols to ignore could itself lead to mistakes.

Yeah, that's not cool, but this test is still a progress for all the cases but slots.

[aartaka]

Okay, I've patched the tests to not check accessor functions (as these are often auto-generated). Now the list of undocumented symbols is much saner:

; Errors:
((#<PACKAGE "NFILES">
  (EXTERNAL-MODIFICATION PROCESS-ERROR INVALID-CHECKSUM *DEFAULT-PROFILE*
   EXISTS-P FETCH-ERROR))
 (#<PACKAGE "NFILES/GPG">
  (*GPG-DEFAULT-RECIPIENT* *GPG-PROGRAM* GPG-UID GPG-KEY)))
Found undocumented exported symbols in 2 packages.

[aartaka]

Is it NASDF 0.1.4 then?

[Ambrevar]

I like the result after skipping accessors, but we should fix the code.

Care to fill up the missing docstrings? Otherwise I can do it later.

[aartaka]

I'll get back to this tomorrow, polishing things up, using built-in MOP thingie, and fixing up the docs!

[aartaka]

All done, merging? I'll squash and rebase, obviously. The only undiscussed thing is whether we should retain :undocumented-symbols-to-ignore, but I believe there are enough exceptional situations (as there are more than one namespace in CL) to keep it, just in case.

[aartaka]

Merged!