symdstools / docsmodifier Goto Github PK

            DocsModifier version 3.6
            last changed: 01.03.2019

This app was created by Symbroson for DroidScript.


**************************************************
                    STRUCTURE
**************************************************

 - introduction
 - file structure
 - how to use
 - source code
   - ternary operators
   - higher order functions


**************************************************
                    INTRODUCTION
**************************************************

    with this tool you can easily edit the
    DroidScript documentation to help all
     users to Understand how DroidScript
     works, which methods are available
        and what you can do with it.


**************************************************
                   FILE STRUCTURE
**************************************************

DocsModifier/
|
|__DocsModifier.js  --  Main js file
|    initialisizes variables, app events,
|    loading functions and some useful
|    help-functions
|
|__GUI.js  --  whole app GUI
|    stores all GUI objects and callbacks
|    in separate global objects
|
|__Dialogs.js  --  all app dialogs
|    stores all dialog objects and callbacks
|    in separate global objects
|
|__Generate.js  --  docs-genarator
|    generates the doc files based on
|    functions*.json and samples/*.txt
|
|__assets/  --  copied to /sdcard/DocsModifier/
   |
   |__app.js  --  DroidScript's app object
   |
   |__functions*.json  --  app.* functions data
   |    required by Generator.js!
   |
   |__categories*.json
   |    json file with the sections content
   |
   |__samples/*.txt  --  doc examples
   |    required by Generator.js!
   |
   |__docs*/  --  language related docs folder
      |
      |__*.htm  --  main pages
      |
      |__app/*.htm  --  app* function docs
      |
      |__detailed/*.htm  --  "old" docs


**************************************************
                    HOW-TO-USE
**************************************************

**** starting ****

When you start the app the first time it shows the
 Readme dialog first. After that the app freezes a
   short time because it extracts the assets to
   /sdcard/DocsModifier/. After the extracting
  process you are asked to choose your preferred
  language. You can change it later if you want.


**** main page ****

	'choose language' button
		select your prreferred language
		or add a new one

	'Import' button
		Import zip files generated from this app
		directly to DroidScript or /DocsModifier/,
		epningo the content.
		ATTENTION!: files will be overwritten

	'Export' button
		Export functions.json and the samples folder
		or the generated docs via mail or save them
		to your Downloads/ folder.
		You can also export your generated docs
		directly to DroidScript.

	'Readme' button
		Shows this dialog to read the readme or
		the license file.

	'generate all docs' button
		Generates the doc files of all app funcions
		dependen on the current selected language.

	'full docs preview' button
		Shows a diog with a preview of your current
		generated docs like in DroidScript.

	'sections' list
		Naviate through the app object.
		use longtouch to add or remove
		functions or sections

		red marked items in the functions
		list means that there is smth missing


**** edit docs page ****

	'edit sample snippets' button
		shows the 'edit examples page'

	'Save andd generate' button
		saves and generates the current doc file

	'Preview' button
		show a preview of the current  doc file

	'return value' button
		select a return value from the dialog
		You can specify the value on numbers, strings,
		lists and objects, for example for options

	'description' text edit
		edit the description of the current function
		you can alse use tabs, spaces and linebreaks.

	'Parameters' list
		select an item to change the return type
		of a parameter or add/remove them via
		longpress or the '+' item

	'Subfunctions' list
		add, remove and edit subfunctions of an
		app function. The layout will not switch,
		just the input field texts will change

		red marked items in the subfunctions
		list means that there is smth missing

**** edit examples page ****

	'code' text edit
		edit the code of an example snippet.
		Please pay attention on the example rules!

	'bold' button
		adds a <b&rt;bold>/b> tag around the selected
		text area and removes the old one if it exists.

	'samples' list
		add, remove and edit examples using
		longtouch or the '+' item
		


**************************************************
                    SOURCE CODE
**************************************************

         In the following I want to explain
         some special things I have done in
           my code for reducing the size,
      performance or because of other reasons


**** ternary operators ****

	Ternary operators are an excellent
	way for shorting if conditions.
	Instead of using long conditions
	and store values etc. - use ternary
	operators!

	Syntax:
		var foo = cond? val_true : val_false;

	Example:
		var ran = Math.random();
		alert( ran + ( ran<0.5? " < " : " > " ) + " 0.5!" );


**** higher order functions ****

	You may have seen lines using .sort(), .join()
	or .map(). This three functions are higher order
	functions of different data structures. They can
	do different things with them. Here I want to
	explain some which I have used:

	Array.sort
		As the function name says - it sorts an array
		ruled by the function given as argument. The
		argument function should take two variables as
		arguments which have to be compared. Also it
		should return an integer value of 1 or -1
		dependent on it should be moved up or down.
		At the end it returns a new sorted array.

		Syntax:
			Array.sort( function( a, b ) );

		Example:
			var arr = [5,2,4,1,3].sort( function( a, b ) {
				return a > b? 1 : -1;
			} );
			// arr = [1, 2, 3, 4, 5]

	Array.join
		This one is very useful if you want to convert
		an array into a string, each item divided by
		an other string. It is the opposite of
		String.split() which splits up the string on
		given positions.

		Syntax:
			Array.join( String );

		Example:
			var str = [1,2,3,4,5].join( ", " );
			// str = "1, 2, 3, 4, 5"

	Array.filter
		Here the argument function just takes one
		parameter. It should return a boolean value -
		true if it matches the condition inside, or
		false. it returns a new filtered array.

		Syntax:
			Array.filter( function( n ) );

		Example:
			var arr = [1,2,3,4,5].filter( function( n ) {
				return n / 2 != 0;
			} );
			// arr = [1, 3, 5]

	Array.forEach
		This one iterates through the array without a
		counter but the item itself. This can be
		useful if you want to do smth based on the
		data inside the array without moyfying it. It
		also does not return any value.

		Syntax:
			Array.forEach( function( item ) );

		Example:
			var arr = [];
			[1,2,3,4,5].forEach( function( item ) {
				arr.push( item * 2 );
			} );
			// arr = [2, 4, 6, 8, 10]

	Array.map
		Obviously the last example of forEach was very
		bad. Couldn't it work easier?! Of course it
		could! Using Array.map. The argument function
		becomes the item as argument - like forEach.
		The difference is that you can return a value
		which will be inserted into a new array which
		was returned at the end.

		Syntax:
			Array.map( function(item) );

			Example:
			var arr = [1,2,3,4,5].map( function( n ) {
				return n * 2;
			} );
			// arr = [2, 4, 6, 8, 10]

___________________________________________________

  Here's the end of my README. If you still have
      questions please contact me directly at
             "[email protected]"

                   best regards,
                     Symbroson
___________________________________________________