--- loncom/interface/loncommon.pm	2016/07/01 19:59:35	1.1248
+++ loncom/interface/loncommon.pm	2016/07/08 17:21:01	1.1249
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # a pile of common routines
 #
-# $Id: loncommon.pm,v 1.1248 2016/07/01 19:59:35 raeburn Exp $
+# $Id: loncommon.pm,v 1.1249 2016/07/08 17:21:01 damieng Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -10883,7 +10883,23 @@ sub get_env_multiple {
     return(@values);
 }
 
+# Looks at given dependencies, and returns something depending on the context.
+# For coursedocs paste, returns (undef, $counter, $numpathchg, \%existing).
+# For syllabus rewrites, returns (undef, $counter, $numpathchg, \%existing, \%mapping).
+# For all other contexts, returns ($output, $counter, $numpathchg).
+# $output: string with the HTML output. Can contain missing dependencies with an upload form, existing dependencies, and dependencies no longer in use.
+# $counter: integer with the number of existing dependencies when no HTML output is returned, and the number of missing dependencies when an HTML output is returned.
+# $numpathchg: integer with the number of cleaned up dependency paths.
+# \%existing: hash reference clean path -> 1 only for existing dependencies.
+# \%mapping: hash reference clean path -> original path for all dependencies.
+# @param {string} actionurl - The path to the handler, indicative of the context.
+# @param {string} state - Can contain HTML with hidden inputs that will be added to the output form.
+# @param {hash reference} allfiles - List of file info from lonnet::extract_embedded_items
+# @param {hash reference} codebase - undef, not modified by lonnet::extract_embedded_items ?
+# @param {hash reference} args - More parameters ! Possible keys: error_on_invalid_names (boolean), ignore_remote_references (boolean), current_path (string), docs_url (string), docs_title (string), context (string)
+# @return {Array} - array depending on the context (not a reference)
 sub ask_for_embedded_content {
+    # NOTE: documentation was added afterwards, it could be wrong
     my ($actionurl,$state,$allfiles,$codebase,$args)=@_;
     my (%subdependencies,%dependencies,%mapping,%existing,%newfiles,%pathchanges,
         %currsubfile,%unused,$rem);
@@ -10899,6 +10915,9 @@ sub ask_for_embedded_content {
     my $heading = &mt('Upload embedded files');
     my $buttontext = &mt('Upload');
 
+    # fills these variables based on the context:
+    # $navmap, $cdom, $cnum, $udom, $uname, $url, $toplevel, $getpropath,
+    # $path, $fileloc, $title, $rem, $filename
     if ($env{'request.course.id'}) {
         if ($actionurl eq '/adm/dependencies') {
             $navmap = Apache::lonnavmaps::navmap->new();
@@ -10983,6 +11002,16 @@ sub ask_for_embedded_content {
         $fileloc = &Apache::lonnet::filelocation('',$toplevel).'/';
         $fileloc =~ s{^/}{};
     }
+    
+    # parses the dependency paths to get some info
+    # fills $newfiles, $mapping, $subdependencies, $dependencies
+    # $newfiles: hash URL -> 1 for new files or external URLs
+    # (will be completed later)
+    # $mapping:
+    #   for external URLs: external URL -> external URL
+    #   for relative paths: clean path -> original path
+    # $subdependencies: hash clean path -> clean file name -> 1 for relative paths in subdirectories
+    # $dependencies: hash clean or not file name -> 1 for relative paths not in subdirectories
     foreach my $file (keys(%{$allfiles})) {
         my $embed_file;
         if (($path eq "/uploaded/$cdom/$cnum/portfolio/syllabus") && ($file =~ m{^\Q$path/\E(.+)$})) {
@@ -11025,6 +11054,19 @@ sub ask_for_embedded_content {
             }
         }
     }
+    
+    # looks for all existing files in dependency subdirectories (from $subdependencies filled above)
+    # and lists
+    # fills $currsubfile, $pathchanges, $existing, $numexisting, $newfiles, $unused
+    # $currsubfile: hash clean path -> file name -> 1 for all existing files in the path
+    # $pathchanges: hash clean path -> 1 if the file in subdirectory exists and
+    #                                    the path had to be cleaned up
+    # $existing: hash clean path -> 1 if the file exists
+    # $numexisting: number of keys in $existing
+    # $newfiles: updated with clean path -> 1 for files in subdirectories that do not exist
+    # $unused: only for /adm/dependencies, hash clean path -> 1 for existing files in
+    #                                      dependency subdirectories that are
+    #                                      not listed as dependencies, with some exceptions using $rem
     my $dirptr = 16384;
     foreach my $path (keys(%subdependencies)) {
         $currsubfile{$path} = {};
@@ -11100,6 +11142,9 @@ sub ask_for_embedded_content {
             }
         }
     }
+    
+    # fills $currfile, hash file name -> 1 or [$size,$mtime]
+    # for files in $url or $fileloc (target directory) in some contexts
     my %currfile;
     if (($actionurl eq '/adm/portfolio') ||
         ($actionurl eq '/adm/coursegrp_portfolio')) {
@@ -11138,6 +11183,8 @@ sub ask_for_embedded_content {
             }
         }
     }
+    # updates $pathchanges, $existing, $numexisting, $newfiles and $unused for files that
+    # are not in subdirectories, using $currfile
     foreach my $file (keys(%dependencies)) {
         if (exists($currfile{$file})) {
             unless ($mapping{$file} eq $file) {
@@ -11166,6 +11213,8 @@ sub ask_for_embedded_content {
             $unused{$file} = 1;
         }
     }
+    
+    # returns some results for coursedocs paste and syllabus rewrites ($output is undef)
     if (($actionurl eq '/adm/coursedocs') && (ref($args) eq 'HASH') &&
         ($args->{'context'} eq 'paste')) {
         $counter = scalar(keys(%existing));
@@ -11177,6 +11226,12 @@ sub ask_for_embedded_content {
         $numpathchg = scalar(keys(%pathchanges));
         return ($output,$counter,$numpathchg,\%existing,\%mapping);
     }
+    
+    # returns HTML otherwise, with dependency results and to ask for more uploads
+    
+    # $upload_output: missing dependencies (with upload form)
+    # $modify_output: uploaded dependencies (in use)
+    # $delete_output: files no longer in use (unused files are not listed for londocs, bug?)
     foreach my $embed_file (sort {lc($a) cmp lc($b)} keys(%newfiles)) {
         if ($actionurl eq '/adm/dependencies') {
             next if ($embed_file =~ m{^\w+://});