Updated documentation

Author: Scott Ware

address.go

@@ -147,7 +147,7 @@ func (p *PaloAlto) AddressGroups(devicegroup ...string) (*AddressGroups, error)
 	return &groups, nil
 }
 
-// CreateAddress will add a new address object to the device. Addrtype should be one of: ip, range, or fqdn. If creating an address
+// CreateAddress will add a new address object to the device. Addrtype should be one of ip, range, or fqdn. If creating an address
 // object on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) CreateAddress(name, addrtype, address, description string, devicegroup ...string) error {
 	var xmlBody string

network.go

@@ -48,8 +48,8 @@ type ProxyID struct {
 }
 
 // CreateLayer3Interface adds a new layer-3 interface or sub-interface to the device. If adding a sub-interface,
-// be sure to append the VLAN tag to the interface name like so: ethernet1/1.700. You must specify the subnet mask in
-// CIDR notation when specifying the IP address, i.e.: 1.1.1.1/32.
+// be sure to append the VLAN tag to the interface name (e.g. ethernet1/1.700). You must also specify the subnet mask in
+// CIDR notation when specifying the IP address.
 func (p *PaloAlto) CreateLayer3Interface(ifname, ipaddress string, comment ...string) error {
 	var xmlBody string
 	var reqError requestError
@@ -91,11 +91,11 @@ func (p *PaloAlto) CreateLayer3Interface(ifname, ipaddress string, comment ...st
 	return nil
 }
 
-// CreateInterface creates the given interface type specified in the "iftype" parameter: tap, vwire, layer2, layer3, vlan,
-// loopback or tunnel. If adding a sub-interface, be sure to append the VLAN tag to the interface name like so: ethernet1/1.700.
+// CreateInterface creates the given interface type specified in the `iftype`` parameter (e.g. tap, vwire, layer2, layer3, vlan,
+// loopback or tunnel). If adding a sub-interface, be sure to append the VLAN tag to the interface name (e.g. ethernet1/1.700).
 // The (optional) ipaddr parameter allows you to assign an IP address to a layer 3/vlan/loopback or tunnel interface, or an
-// IP classifier to a virtual-wire sub-interface. You do not need to specify the ipaddr parameter on a "tap" or "layer2" interface type.
-// Note that you must specify the subnet mask in CIDR notation when including an IP address, i.e.: 1.1.1.1/24.
+// IP classifier to a virtual-wire sub-interface. You do not need to specify the ipaddr parameter on a tap or layer2 interface type.
+// Note that you must specify the subnet mask in CIDR notation when including an IP address.
 func (p *PaloAlto) CreateInterface(iftype, ifname, comment string, ipaddr ...string) error {
 	var xmlBody string
 	var xpath string
@@ -257,7 +257,7 @@ func (p *PaloAlto) CreateInterface(iftype, ifname, comment string, ipaddr ...str
 }
 
 // DeleteInterface removes an interface or sub-interface from the device. You must specify the interface
-// type in the iftype parameter: tap, vwire, layer2, layer3, vlan, loopback or tunnel.
+// type in the iftype parameter (e.g. tap, vwire, layer2, layer3, vlan, loopback or tunnel).
 func (p *PaloAlto) DeleteInterface(iftype, ifname string) error {
 	var reqError requestError
 	var xpath string
@@ -326,8 +326,8 @@ func (p *PaloAlto) DeleteInterface(iftype, ifname string) error {
 	return nil
 }
 
-// CreateZone will add a new zone to the device. Zonetype must be one of: tap, vwire, layer2, layer3. If
-// you wish to enable user-id on the zone, specify "true" for the userid parameter, "false" if not.
+// CreateZone will add a new zone to the device. Zonetype must be one of tap, vwire, layer2, layer3. If
+// you wish to enable user-id on the zone, specify true for the userid parameter, false if not.
 func (p *PaloAlto) CreateZone(name, zonetype string, userid bool) error {
 	var xmlBody string
 	var reqError requestError
@@ -394,8 +394,8 @@ func (p *PaloAlto) DeleteZone(name string) error {
 	return nil
 }
 
-// AddInterfaceToZone adds an interface or interfaces to the given zone. zonetype must be one of: tap, vwire, layer2, layer3.
-// Separate multiple interfaces using a comma, i.e.: "ethernet1/2, ethernet1/3"
+// AddInterfaceToZone adds an interface or interfaces to the given zone. Zonetype must be one of tap, vwire, layer2, layer3.
+// Separate multiple interfaces using a comma (e.g. "ethernet1/2, ethernet1/3").
 func (p *PaloAlto) AddInterfaceToZone(name, zonetype, ifname string) error {
 	var xmlBody string
 	var reqError requestError
@@ -542,7 +542,7 @@ func (p *PaloAlto) DeleteVirtualRouter(vr string) error {
 }
 
 // AddInterfaceToVirtualRouter will add an interface or interfaces to the given virtual-router. Separate multiple
-// interfaces using a comma, i.e.: "ethernet1/2, ethernet1/3"
+// interfaces using a comma (e.g. "ethernet1/2, ethernet1/3").
 func (p *PaloAlto) AddInterfaceToVirtualRouter(vr, ifname string) error {
 	var xmlBody string
 	var reqError requestError
@@ -602,7 +602,7 @@ func (p *PaloAlto) RemoveInterfaceFromVirtualRouter(vr, ifname string) error {
 }
 
 // CreateStaticRoute adds a new static route to a given virtual-router. For the destination, you must
-// include the mask, i.e. "192.168.0.0/24" or "0.0.0.0/0." For nexthop, you can also specify an interface
+// include the mask (e.g. "192.168.0.0/24" or "0.0.0.0/0"). For nexthop, you can also specify an interface
 // instead of an IP address. You can optionally specify a metric for the route (default metric is 10).
 func (p *PaloAlto) CreateStaticRoute(vr, name, destination, nexthop string, metric ...int) error {
 	var xmlBody string
@@ -705,7 +705,7 @@ func (p *PaloAlto) CreateVlan(name string, vlaninterface ...string) error {
 }
 
 // AddInterfaceToVlan will add an interface or interfaces to the given vlan. Separate multiple
-// interfaces using a comma, i.e.: "ethernet1/2, ethernet1/3"
+// interfaces using a comma (e.g. "ethernet1/2, ethernet1/3").
 func (p *PaloAlto) AddInterfaceToVlan(vlan, ifname string) error {
 	var xmlBody string
 	var reqError requestError
@@ -847,7 +847,9 @@ func (p *PaloAlto) DeleteVwire(name string) error {
 
 // ARPTable will gather all of the ARP entires on the device. Without any parameters, it will return all ARP entries.
 // You can specify an interface name for the option parameter if you choose to only view the ARP entries for that specific
-// interface (i.e. "ethernet1/1.200" or "ethernet1/21"). Status codes are as follows: s - static, c - complete, e - expiring, i - incomplete.
+// interface (e.g. "ethernet1/1.200" or "ethernet1/21"). Status codes are as follows:
+//
+// s - static, c - complete, e - expiring, i - incomplete.
 func (p *PaloAlto) ARPTable(option ...string) (*ARPTable, error) {
 	var arpTable ARPTable
 	command := "<show><arp><entry name = 'all'/></arp></show>"

objects.go

@@ -26,7 +26,7 @@ type CustomURL struct {
 }
 
 // Recurrance contains the information for external dynamic lists when it comes to how often they are downloaded. Method
-// must be one of: five-minute, hourly, daily, weekly, monthly. DayOfWeek is the name of the day, such as "tuesday." DayOfMonth
+// must be one of five-minute, hourly, daily, weekly, monthly. DayOfWeek is the name of the day, such as "tuesday." DayOfMonth
 // is specified as a number, ranging from 1-31. Hour must be in 23-hour format, such as "03" for 3 am. The hourly and five-minute
 // methods do not require any additional fields. DayOfWeek and DayOfMonth both require the Hour field as well.
 type Recurrance struct {
@@ -177,7 +177,7 @@ func (p *PaloAlto) URLCategory(devicegroup ...string) (*URLCategory, error) {
 }
 
 // CreateURLCategory creates a custom URL category to be used in a policy. When specifying multiple URL's, use a
-// []string variable for the url parameter (i.e. members := []string{"www.*.com", "*.somesite.net"}). If creating a
+// []string variable for the url parameter (e.g. members := []string{"www.*.com", "*.somesite.net"}). If creating a
 // URL category on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) CreateURLCategory(name string, urls []string, description string, devicegroup ...string) error {
 	var xpath string
@@ -225,7 +225,7 @@ func (p *PaloAlto) CreateURLCategory(name string, urls []string, description str
 	return nil
 }
 
-// EditURLCategory adds or removes URL's from the given custom URL category. Action must be "add" or "remove." If editing
+// EditURLCategory adds or removes URL's from the given custom URL category. Action must be add or remove If editing
 // a URL category on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) EditURLCategory(action, url, name string, devicegroup ...string) error {
 	var xpath string
@@ -337,8 +337,8 @@ func (p *PaloAlto) DeleteURLCategory(name string, devicegroup ...string) error {
 	return nil
 }
 
-// EditGroup will add or remove objects from the specified group type (i.e., "address" or "service"). Action must be
-// "add" or "remove." If editing a group on a Panorama device, specify the device-group as the last parameter.
+// EditGroup will add or remove objects from the specified group type (e.g., "address" or "service"). Action must be
+// add or remove. If editing a group on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) EditGroup(objecttype, action, object, group string, devicegroup ...string) error {
 	var xmlBody string
 	var xpath string
@@ -430,8 +430,11 @@ func (p *PaloAlto) EditGroup(objecttype, action, object, group string, devicegro
 }
 
 // RenameObject will rename the given object from oldname to the newname. You can rename the following
-// object types: address, address-groups, service, service-groups, tags. If renaming objects on a
-// Panorama device, specify the device-group as the last parameter.
+// object types:
+//
+// address, address-groups, service, service-groups, tags.
+//
+// If renaming objects on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) RenameObject(oldname, newname string, devicegroup ...string) error {
 	var xpath string
 	var reqError requestError
@@ -769,9 +772,13 @@ func (p *PaloAlto) RenameObject(oldname, newname string, devicegroup ...string)
 	return nil
 }
 
-// CreateExternalDynamicList will create an external dynamic list on the device. Listtype must be one of: ip, domain, or url. Configuring the
-// recurrance requires you to use the Recurrance struct when passing the configuration for this parameter - please see the documentation for that struct.
-// If creating an EDL on a Panorama device, specify the device-group as the last parameter.
+// CreateExternalDynamicList will create an external dynamic list on the device. Listtype must be one of:
+//
+// ip, domain, or url
+//
+// Configuring the recurrance requires you to use the `Recurrance` struct when passing the configuration for this
+// parameter - please see the documentation for that struct. If creating an EDL on a Panorama device, specify
+// the device-group as the last parameter.
 func (p *PaloAlto) CreateExternalDynamicList(listtype string, name string, url string, recurrance *Recurrance, devicegroup ...string) error {
 	var xpath string
 	var reqError requestError
@@ -925,9 +932,12 @@ func (p *PaloAlto) Tags(devicegroup ...string) (*Tags, error) {
 
 }
 
-// CreateTag will add a new tag to the device. You can use the following colors: Red, Green, Blue, Yellow, Copper,
-// Orange, Purple, Gray, Light Green, Cyan, Light Gray, Blue Gray, Lime, Black, Gold, Brown. If creating a tag on a
-// Panorama device, specify the device-group as the last parameter.
+// CreateTag will add a new tag to the device. You can use the following colors:
+//
+// Red, Green, Blue, Yellow, Copper, Orange, Purple, Gray, Light Green, Cyan, Light Gray,
+// Blue Gray, Lime, Black, Gold, Brown.
+//
+// If creating a tag on a Panorama device, specify the device-group as the last parameter.
 func (p *PaloAlto) CreateTag(name, color, comments string, devicegroup ...string) error {
 	var xmlBody string
 	var xpath string
@@ -1767,7 +1777,7 @@ func (p *PaloAlto) SecurityProfileGroups() (*SecurityGroups, error) {
 }
 
 // ApplyLogForwardingProfile will apply a Log Forwarding profile to every rule in the policy for the given device-group.
-// If you wish to apply it to a single rule, instead of every rule in the policy, you can optionally specify the rule name as the last parameter.
+// If you wish to apply it to a single rule, instead of every rule in the policy, you can (optionally) specify the rule name as the last parameter.
 // For policies with a large number of rules, this process may take a few minutes to complete.
 func (p *PaloAlto) ApplyLogForwardingProfile(logprofile, devicegroup string, rule ...string) error {
 	if p.DeviceType != "panorama" {
@@ -1919,10 +1929,14 @@ func (p *PaloAlto) ApplyLogForwardingProfile(logprofile, devicegroup string, rul
 	return nil
 }
 
-// ApplySecurityProfile will apply the following security profiles: URL Filtering, File-Blocking, Antivirus, Anti-Spyware, Vulnerability, Wildfire
-// to every rule in the policy for the given device-group. If you wish to apply it to a single rule, instead of every
-// rule in the policy, you can optionally specify the rule name as the last parameter. You can also specify a security group profile instead of individual profiles.
-// This is done by ONLY populating the "Group" field in the SecurityProfiles struct. For policies with a large number of rules,
+// ApplySecurityProfile will apply the following security profiles to every rule in teh policy for the given
+// device-group:
+//
+// URL Filtering, File-Blocking, Antivirus, Anti-Spyware, Vulnerability, Wildfire
+//
+// If you wish to apply it to a single rule, instead of every rule in the policy, you can (optionally) specify
+// the rule name as the last parameter. You can also specify a security group profile instead of individual profiles.
+// This is done by ONLY populating the Group field in the SecurityProfiles struct. For policies with a large number of rules,
 // this process may take a few minutes to complete.
 func (p *PaloAlto) ApplySecurityProfile(secprofiles *SecurityProfiles, devicegroup string, rule ...string) error {
 	if p.DeviceType != "panorama" {
@@ -2251,27 +2265,12 @@ func (p *PaloAlto) ApplySecurityProfile(secprofiles *SecurityProfiles, devicegro
 }
 
 // CreateObjectsFromCsv takes a CSV file and creates the given address or service objects, and
-// address or service groups defined within. See https://github.com/scottdware/go-panos#creating-objects-from-a-csv-file
-// for more detailed examples.
-//
-// The format of the CSV file must follow this layout:
+// address or service groups defined within. The format of the CSV file must follow this layout:
 //
 // name,type,value,description (optional),tag (optional),device-group
 //
-// For the type column, you can specify: 'ip', 'range', 'fqdn' for address objects, and 'tcp' or 'udp' for service
-// objects. For address group objects, you must specify either 'static' or 'dynamic'. And for service groups,
-// you must specify 'service'. The description and tag columns are optional, so just leave them blank if you do not
-// need them.
-//
-// If you are creating an address group, then the value field must contain the following:
-//
-// For a static address group: list of members to add separated by a space, i.e.: ip-host1 ip-net1 fqdn-example.com
-// For a dynamic address group: the criteria (tags) to match on, i.e.: web-servers or db-servers and linux
-//
-// If you are creating a service group, then the value field must contain a list of service objects to add, separated by a space.
-//
-// If any of the objects you are creating need to be shared objects, then specify the word "shared" in the device-group (last)
-// column.
+// See https://github.com/scottdware/go-panos#creating-objects-from-a-csv-file
+// for complete documentation and examples.
 func (p *PaloAlto) CreateObjectsFromCsv(file string) error {
 	c, err := easycsv.Open(file)
 	if err != nil {
@@ -2455,16 +2454,12 @@ func (p *PaloAlto) CreateObjectsFromCsv(file string) error {
 }
 
 // ModifyGroupsFromCsv takes a CSV file and modifies the given address or service groups with the
-// specified action. See https://github.com/scottdware/go-panos#modifying-object-groups-from-a-csv-file
-// for more detailed examples.
-//
-// The format of the CSV file must follow this layout:
+// specified action. The format of the CSV file must follow this layout:
 //
 // grouptype,action,object-name,group-name,device-group
 //
-// For the grouptype column, you must specify 'address' or 'service'. Action must be either 'add' or 'remove'.
-//
-// If modifying groups on a Panorama device, specify the device-group column in the CSV file.
+// See https://github.com/scottdware/go-panos#modifying-object-groups-from-a-csv-file
+// for complete documentation and examples.
 func (p *PaloAlto) ModifyGroupsFromCsv(file string) error {
 	c, err := easycsv.Open(file)
 	if err != nil {

panorama.go

@@ -108,7 +108,7 @@ func (p *PaloAlto) Devices() (*Devices, error) {
 }
 
 // DeviceGroups returns information about all of the device-groups in Panorama, and what devices are
-// linked to them, along with their information. You can optionally specify a specific device-group
+// linked to them, along with detailed information about each device. You can (optionally) specify a specific device-group
 // if you wish.
 func (p *PaloAlto) DeviceGroups(devicegroup ...string) (*DeviceGroups, error) {
 	var devices DeviceGroups