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.
Newer versions do actually allow this using the doc string;
For instance, I have this script in a Library:
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:
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
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.
So that answers one question.
What I've been doing to separate the defs more clearly is using a full line of "#"
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-
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)
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.
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.)
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:
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:
I'm using this resource for guidance.
? No idea
You provide two return types. The superset is "any".
Because python/jython returns one object. That can be tuple of two items, but you'd have to say so.
Seems like Google's formatting standards simply don't really support it. Nicely formatting tuples i mean.
Do not imitate older ‘NumPy style’ (example), 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 
