docs: 📝 Properly document craft_artefact

lib/comfpile/core.rb

@@ -21,6 +21,21 @@ module Comfpile
             @artefacts.dig(stage, file)
         end
 
+        # Create or find a new artefact.
+        #
+        # This will first see if a given artefact matching
+        # the stage and target descriptions already exists, and
+        # will return it, if found. Otherwise it will 
+        # consult all given artefact crafting engines to
+        # see if a new artefact can be created, which will be returned.
+        #
+        # If no artefact can be made, nil is returned
+        #
+        # @param [Symbol, String] stage State that shall be created (e.g. :parsed, :compiled, etc.)
+        # @param [String] file File or other target that shall be looked at (e.g. "main.cpp")
+        #
+        # @return [Comfpile::Artefact, nil] Found or created artefact, or nil if nothing could be done
+        #
         def craft_artefact(stage, file = :none)
             artefact = find_artefact(stage, file)