Add some basic jsdoc based documentation, issue #64, part 5

fiduswriter · Nov 17, 2013 · 2d49ed9 · 2d49ed9
1 parent 7aab4db
commit 2d49ed9
Show file tree

Hide file tree

Showing 9 changed files with 132 additions and 14 deletions.
diff --git a/account/static/js/contact-helpers.js b/account/static/js/contact-helpers.js
@@ -1,5 +1,30 @@
+/**
+ * @file Sets up the contacts management.
+ * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
+ *
+ * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
+ *
+ * @license This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
+ *
+ */
+
 (function () {
     var exports = this,
+    /** 
+  * Helper functions for adding and removing contacts. TODO 
+  * @namespace contactHelpers
+  */
         contactHelpers = {};
 
     //template for the list of teammembers

diff --git a/account/static/js/contacts.js b/account/static/js/contacts.js
@@ -1,3 +1,25 @@
+/**
+ * @file Sets team member page
+ * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
+ *
+ * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
+ *
+ * @license This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
+ *
+ */
+
+
 $(function() {
     //intialize the teammember table
     $('#team-table tbody').append(contactHelpers.tmp_teammember({'members': teammembers}));

diff --git a/account/static/js/edit_profile.js b/account/static/js/edit_profile.js
@@ -1,4 +1,25 @@
-//edit user
+/**
+ * @file Sets up the user edit page.
+ * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
+ *
+ * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
+ *
+ * @license This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
+ *
+ */
+
+/** Save changes to user account. */
 function editUser(post_data) {
     $.ajax({
         url : '/account/save/',

diff --git a/account/static/js/profile-templates.js b/account/static/js/profile-templates.js
@@ -1,7 +1,28 @@
+/**
+ * @file Templates for editing user.
+ * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
+ *
+ * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
+ *
+ * @license This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
+ *
+ */
+/** A template to confirm the deletion of a user avatar. */
 var tmp_confirm_delete_avatar = '<div id="confirmdeletion" title="'
     + gettext('Confirm deletion') + '"><p>'
     + gettext('Delete the avatar') + '?</p></div>';
-
+/** A template to change the user avatar. */
 var tmp_change_avatar_dialog = '<div id="change-avatar-dialog" title="' + gettext('Upload your profile picture') + '">\
         <form id="avatar-uploader-form" method="post" enctype="multipart/form-data" class="ajax-upload">\
             <input type="file" id="avatar-uploader" name="avatar" required />\
@@ -11,12 +32,12 @@ var tmp_change_avatar_dialog = '<div id="change-avatar-dialog" title="' + gettex
             <label id="uploaded-avatar-name" class="ajax-upload-label"></label>\
         </form>\
     </div>';
-
+/** A template for the confirmation dialog to delete a user account. */
 var tmp_delete_user_dialog = '<div id="confirmaccountdeletion" title="'
     + gettext('Confirm deletion') + '"><p>'
     + gettext('Really delete your account? Type in your username below to confirm deletion.') +
     '</p><input type="text" id="username-confirmation"></div>';
-
+/** A template for the change email dialog of the user account. */
 var tmp_change_email_dialog = '<div id="fw-add-email-dialog" title="' + gettext('Add Email') + '">\
         <table class="ui-dialog-content-table"><tbody>\
             <tr><td>\
@@ -28,11 +49,11 @@ var tmp_change_email_dialog = '<div id="fw-add-email-dialog" title="' + gettext(
             <tr><td><span id="fw-add-email-error" class="warning"></span></td></tr>\
         </tbody></table>\
     </div>';
-
+/** A template for the delete email dialog of the user account. */
 var tmp_delete_email_dialog = _.template('<div id="fw-confirm-email-dialog" title="<%= title %>">\
         <p><%- text %></p>\
     </div>');
-
+/** A template for the change password dialog of the user account. */
 var tmp_change_pwd_dialog = '<div id="fw-change-pwd-dialog" title="' + gettext('Change Password') + '">\
         <table class="ui-dialog-content-table"><tbody>\
             <tr><td><form id="fw-password-change-form" action="" method="post" onsubmit="return false;">\

diff --git a/account/static/js/show_profile.js b/account/static/js/show_profile.js
@@ -1,3 +1,25 @@
+/**
+ * @file Handles the user profile page.
+ * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
+ *
+ * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
+ *
+ * @license This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
+ *
+ */
+
+
 $(document).ready(function() {
     var changeAvatarDialog = function() {
         $('body').append(tmp_change_avatar_dialog   );

diff --git a/menu/static/js/menubase.js b/menu/static/js/menubase.js
@@ -1,4 +1,5 @@
 /**
+ * @file Sets up the handling of the menu on the menu pages (almost all pages, except the editor).
  * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
  *
  * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.

diff --git a/usermedia/static/js/usermedia-helpers.js b/usermedia/static/js/usermedia-helpers.js
@@ -1,4 +1,5 @@
 /**
+ * @file Sets up the user media page.
  * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
  *
  * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
@@ -20,6 +21,9 @@
 
 (function () {
     var exports = this,
+ /** Helper functions for user added images/SVGs. TODO
+  * @namespace usermediaHelpers
+  */
         usermediaHelpers = {};
 
     usermediaHelpers.createImage = function (post_data) {

diff --git a/usermedia/static/js/usermedia-simplelist-template-dialogs.js b/usermedia/static/js/usermedia-simplelist-template-dialogs.js
@@ -1,4 +1,5 @@
 /**
+ * @file Templates for a simple image overview within the editor
  * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
  *
  * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
@@ -18,7 +19,7 @@
  *
  */
 
-// overwrite this variable for the image list in the editor
+/** Simpler image overview table for use in editor. */
 var tmp_usermedia_table = _.template('\
                 <tr id="Image_<%- id %>" class="<% _.each(cats, function(cat) { %>cat_<%- cat %> <% }) %>" >\
                      <td class="type" style="width:100px;">\

diff --git a/usermedia/static/js/usermedia-template-dialogs.js b/usermedia/static/js/usermedia-template-dialogs.js
@@ -1,4 +1,5 @@
 /**
+ * @file Templates for the Images overview page
  * @copyright This file is part of <a href='http://www.fiduswriter.org'>Fidus Writer</a>.
  *
  * Copyright (C) 2013 Takuto Kojima, Johannes Wilm.
@@ -17,12 +18,12 @@
  * along with this program.  If not, see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>.
  *
  */
-
+/** A template to edit image categories. */
 var tmp_usermedia_editcategories = _.template('\
     <div id="editCategories" title="<%- dialogHeader %>">\
         <table id="editCategoryList" class="fw-dialog-table"><tbody><%= categories %></tbody></table>\
     </div>');
-
+/** A template for the image category edit form. */
 var tmp_usermedia_categoryforms = _.template('\
     <% _.each(categories, function(cat) { %>\
     <tr id="categoryTr_<%- cat.id %>" class="fw-list-input">\
@@ -38,7 +39,7 @@ var tmp_usermedia_categoryforms = _.template('\
             <span class="fw-add-input icon-addremove"></span>\
         </td>\
     </tr>');
-
+/** A template for image overview list. */
 var tmp_usermedia_table = _.template('\
                 <tr id="Image_<%- id %>" class="<% _.each(cats, function(cat) { %>cat_<%- cat %> <% }) %>">\
                     <td width="30">\
@@ -69,14 +70,14 @@ var tmp_usermedia_table = _.template('\
                         </span>\
                     </td>\
                 </tr>');
-
+/* A template for each image category list item */
 var tmp_usermedia_category_list_item = _.template('\
     <li>\
         <span class="fw-pulldown-item" data-id="<%- iCat.id %>">\
             <%- iCat.category_title %>\
         </span>\
     </li>');
-
+/* A template for the form for the image upload dialog. */
 var tmp_usermedia_upload = _.template('<div id="uploadimage" class="fw-media-uploader" title="<%- action %>">\
     <form action="#" method="post" class="usermediaUploadForm">\
         <div>\
@@ -91,8 +92,8 @@ var tmp_usermedia_upload = _.template('<div id="uploadimage" class="fw-media-upl
         </div></div>\
         <%= categories %>\
     </form></div>');
-
-var tmp_usermedia_upload_categoriy = _.template('<% if(0 < categories.length) { %>\
+/* A template for the image category selection of the image selection dialog. */
+var tmp_usermedia_upload_category = _.template('<% if(0 < categories.length) { %>\
         <div class="fw-media-category">\
             <div><%- fieldTitle %></div>\
             <% _.each(categories, function(cat) { %>\