# Script Library Formatting and Documentation

**URL:** <https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056>\
**Category:** Ignition\
**Tags:** ignition81, scripting\
**Created:** [November 17, 2023, 3:48pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056 "2023-11-17T15:48:05Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![amarks](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/amarks/32/45610_2.png) [@amarks](https://forum.inductiveautomation.com/u/amarks)\
**Post date:** [November 17, 2023, 3:48pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/1 "2023-11-17T15:48:05Z")

</div>

Just curious, how do you guys format your comments to clearly separate and document your different functions within a project library script? I sometimes find it hard to pick out where the next `def` is and wondering if anyone has a good solution, along with general formatting for function description comments.

Would be nice if there was a way for us to add comments that would show up as the "tooltip" when typing the function in a script, the same way the system functions do.

---

<div class="post-metadata">

**Author:** ![lrose](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/lrose/32/62724_2.png) [@lrose](https://forum.inductiveautomation.com/u/lrose)\
**Post date:** [November 17, 2023, 4:42pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/2 "2023-11-17T16:42:49Z")

</div>

> [@amarks](#):
>
> Would be nice if there was a way for us to add comments that would show up as the "tooltip" when typing the function in a script, the same way the system functions do.

Newer versions do actually allow this using the doc string;

For instance, I have this script in a Library:

```auto
def getProcessingOccurences(hours = 23):
	"""	
		Returns:	A list of the number of occrences by hour for the given number of hours.
	"""
	paths = [historicalProvider + p for k,v in tagPaths['processing'].iteritems() for p in v['paths']]
	
	thisHour = system.date.getHour24(system.date.now())
	endDate = system.date.setTime(system.date.now(),thisHour,0,0)
	startDate = system.date.addHours(endDate,-hours)
	
	return system.tag.queryTagHistory(paths,startDate,endDate,aggregationMode = 'CountOn',returnFormat='Tall',columnNames = [path.replace(' ','_').split('/')[-1:][0] for path in paths],intervalHours = 1)

```

Then in the tool tip it looks like this:

 ![image](https://us1.discourse-cdn.com/inductiveautomation/original/3X/6/5/654fb7f3906f2ed359dda64a4feb100abb1b0f6f.png)

---

<div class="post-metadata">

**Author:** ![paul-griffith](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/paul-griffith/32/37249_2.png) [@paul-griffith](https://forum.inductiveautomation.com/u/paul-griffith)\
**Post date:** [November 17, 2023, 4:43pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/3 "2023-11-17T16:43:14Z")

</div>

If you're on 8.1.19 or higher, project library scripts with "docstrings" per Python convention _do_ show up in the autocomplete in other editors:  
[https://docs.inductiveautomation.com/display/DOC81/Scripting+in+Ignition#ScriptinginIgnition-SystemFunctions,Hints,andAutocomplete](https://docs.inductiveautomation.com/display/DOC81/Scripting+in+Ignition#ScriptinginIgnition-SystemFunctions,Hints,andAutocomplete)

If you're on 8.1.32 or higher, if you author those docstrings according to Google's Python style guide, you'll even get nice argument and return value descriptions.

---

<div class="post-metadata">

**Author:** ![amarks](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/amarks/32/45610_2.png) [@amarks](https://forum.inductiveautomation.com/u/amarks)\
**Post date:** [November 17, 2023, 5:01pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/4 "2023-11-17T17:01:29Z")

</div>

So that answers one question.

What I've been doing to separate the `def`s more clearly is using a full line of "#"

 ![image](https://us1.discourse-cdn.com/inductiveautomation/original/3X/4/a/4a4055c7e51c14d6c581793de80f15e852cf34e3.png)

---

<div class="post-metadata">

**Author:** ![Transistor](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/transistor/32/3380_2.png) [@Transistor](https://forum.inductiveautomation.com/u/Transistor)\
**Post date:** [November 17, 2023, 5:22pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/5 "2023-11-17T17:22:40Z")

</div>

Do you have the Script Hint pane showing?

 ![Script hint scope](https://us1.discourse-cdn.com/inductiveautomation/original/3X/2/5/25b6e2af08d6eaf2a80d0485064bdf9869f4a76f.png)

---

<div class="post-metadata">

**Author:** ![bkarabinchak.psi](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/bkarabinchak.psi/32/83567_2.png) [@bkarabinchak.psi](https://forum.inductiveautomation.com/u/bkarabinchak.psi)\
**Post date:** [November 17, 2023, 5:23pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/6 "2023-11-17T17:23:22Z")

</div>

> [@amarks](#):
>
> I sometimes find it hard to pick out where the next `def` is and wondering if anyone has a good solution, along with general formatting for function description comments.

Is it not always at the bottom? If I need to move to a specific spot or want to go to a specific function I just use the sidebar of the project scripting double clicking a function takes me right to it-  
 ![image](https://us1.discourse-cdn.com/inductiveautomation/original/3X/5/4/5492e40a30cff80a968de4b378378dd6a6dea023.png)

The only other organization I do within project libraries - I always put all my business logic (database/tag writing stuff) towards the top, and then any callers of said functions from a GUI towards the bottom (same goes if this is logic called from message handlers - call and handler are at the bottom but any business logic all at the top grouped togeher)

![image](https://us1.discourse-cdn.com/inductiveautomation/original/3X/a/c/acf7049965fbdd93d74732bb6a74a28ccd417d6e.png)

Note that for any vision or perspective specific libraries (`system.gui`, `system.perspective`, etc)they should be called within the function or you'll risk issues depending where you call your script from.

Edit: Now that I think about it, as long as the function is only called from the right scope, I am not even sure `import system.gui/import system.perspective` would be necessary. It's been a while since I wrote the above.

---

<div class="post-metadata">

**Author:** ![pturmel](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/pturmel/32/3295_2.png) [@pturmel](https://forum.inductiveautomation.com/u/pturmel)\
**Post date:** [November 17, 2023, 9:52pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/7 "2023-11-17T21:52:53Z")

</div>

> [@bkarabinchak.psi](#):
>
> I am not even sure `import system.gui/import system.perspective` would be necessary.

Not necessary. Doing `from system.something import *` can be handy in some cases, but otherwise imports just slow your script.

(You still have to import jython stdlib modules. But only those.)

---

<div class="post-metadata">

**Author:** ![richardNZ15](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/richardnz15/32/33373_2.png) [@richardNZ15](https://forum.inductiveautomation.com/u/richardNZ15)\
**Post date:** [December 19, 2023, 10:42pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/8 "2023-12-19T22:42:03Z")

</div>

I seem to have 90% of the tooltip showing correctly, but can't get Returns to work..  
Can someone point out where it is going wrong?

**Script function definition:**

```auto
def calcKPIsAllFJAs(startDate,endDate,dailyMode):
	""" 
	This script compiles overall Finger Joiner Assembler KPI data from all available machine centers.
	
	If a Machine Centre is determined to have not run throughout the period (volume or run minutes = 0), then it won't count towards overall metrics.
	
	Date: Author: Revision:
	20/12/2023 Richard Lee (TCL) Initial
	
	Args:
		startDate (dt): Start date of reporting window.
		endDate (datetime): End date of reporting window.
		dailyMode (bool): TRUE = calculate expected hours based on scheduled time. FALSE = calculate expected hours based on time between time range. 
	
	Returns:
		RawData (dataset): Dataset of all relevant values that went into the calculation.
		AggDataDict (dict): Dictionary of all aggregated "total" values.
	
	Raises:
		
	"""	
	scriptName = "shared.kpi.calcKPIsAllFJAs"
	
	startDateStr = system.date.format(startDate, 'dd/MM/yyyy HH:mm') # Prettify for logger messages
	endDateStr = system.date.format(endDate, 'dd/MM/yyyy HH:mm') # Prettify for logger messages

```

**Tooltip shown:**

 ![image](https://us1.discourse-cdn.com/inductiveautomation/original/3X/5/e/5ee9ec5dcddf058cec500dada57975247cbc8ce3.png)

1. Is there no inherent "date or datetime" type descriptor in Python? all I find are references to the datetime module..
2. Not sure why it says "Returns: any"
3. Not sure why it can't split out the returned arguments like it does for Parameters. I'm not even sure it is possible based on the documentation.

I'm using this resource for guidance.

> **[styleguide](https://google.github.io/styleguide/pyguide.html)**
>
> Style guides for Google-originated open-source projects

---

<div class="post-metadata">

**Author:** ![pturmel](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/pturmel/32/3295_2.png) [@pturmel](https://forum.inductiveautomation.com/u/pturmel)\
**Post date:** [December 19, 2023, 10:48pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/9 "2023-12-19T22:48:49Z")

</div>

1. ? No idea

2. You provide two return types. The superset is "any".

3. Because python/jython returns one object. That can be tuple of two items, but you'd have to say so.

---

<div class="post-metadata">

**Author:** ![richardNZ15](https://sea1.discourse-cdn.com/inductiveautomation/user_avatar/forum.inductiveautomation.com/richardnz15/32/33373_2.png) [@richardNZ15](https://forum.inductiveautomation.com/u/richardNZ15)\
**Post date:** [December 19, 2023, 11:10pm UTC](https://forum.inductiveautomation.com/t/script-library-formatting-and-documentation/82056/10 "2023-12-19T23:10:40Z")

</div>

Seems like Google's formatting standards simply don't really support it. Nicely formatting tuples i mean.

> Do not imitate older ‘NumPy style’ ([example](https://numpy.org/doc/1.24/reference/generated/numpy.linalg.qr.html)), which frequently documented a tuple return value as if it were multiple return values with individual names (never mentioning the tuple).

Perhaps not the most amazing standard to choose for Ignition but ohwell. Maybe IA can tweak it to suit better.

It seems Ignition isn't able to support even simple line breaks after the "Returns" keyword which is a shame, although perhaps that is a bug 🤷‍♂️