Jira (PDOC-277) Ensure that multiline examples are correctly parsed

9 views
Skip to first unread message

Jesse Scott (JIRA)

unread,
May 1, 2019, 6:54:02 PM5/1/19
to puppe...@googlegroups.com
Jesse Scott created an issue
 
Puppet Strings / Bug PDOC-277
Ensure that multiline examples are correctly parsed
Issue Type: Bug Bug
Assignee: Unassigned
Created: 2019/05/01 3:53 PM
Priority: Normal Normal
Reporter: Jesse Scott

Follow up to PDOC-265

From Henrik's comment on that issue:

Examples in regsubst.rb (the 4.x implementation) looks like this:

# @example Get the third octet from the node's IP address:
#
# ```puppet
# $i3 = regsubst($ipaddress,'^(\\d+)\\.(\\d+)\\.(\\d+)\\.(\\d+)$','\\3')
# ```
#
# @example Put angle brackets around each octet in the node's IP address:
#
# ```puppet
# $x = regsubst($ipaddress, /([0-9]+)/, '<\\1>', 'G')
# ```

Note that the example body is one blank line away and not indented. Is that what is causing Puppet Strings to not pick it up? Or is it something else?

Add Comment Add Comment
 
This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93)
Atlassian logo

Jean Bond (JIRA)

unread,
Aug 12, 2019, 7:40:02 PM8/12/19
to puppe...@googlegroups.com
Jean Bond commented on Bug PDOC-277
 
Re: Ensure that multiline examples are correctly parsed

The spacing on the above example has been fixed, but still has issues. I also found an issue with this line in functions:

For example, in the `break` function (starting at line 1):

# Breaks an innermost iteration as if it encountered an end of input.
# This function does not return to the caller.
#
# The signal produced to stop the iteration bubbles up through
# the call stack until either terminating the innermost iteration or
# raising an error if the end of the call stack is reached.
#
# The break() function does not accept an argument.
#
# @example Using `break`
#
# ```puppet
# $data = [1,2,3]
# notice $data.map |$x| { if $x == 3 { break() } $x*10 }
# ```
#
# Would notice the value `[10, 20]`

renders in generated docs output as

Breaks an innermost iteration as if it encountered an end of input.
This function does not return to the caller.
 
The signal produced to stop the iteration bubbles up through
the call stack until either terminating the innermost iteration or
raising an error if the end of the call stack is reached.
 
The break() function does not accept an argument.
 
```puppet
$data = [1,2,3]
notice $data.map |$x| { if $x == 3 { break() } $x*10 }
```
 
Would notice the value `[10, 20]`

Jean Bond (JIRA)

unread,
Aug 12, 2019, 7:40:23 PM8/12/19
to puppe...@googlegroups.com

Jean Bond (JIRA)

unread,
Aug 12, 2019, 8:19:03 PM8/12/19
to puppe...@googlegroups.com
Jean Bond commented on Bug PDOC-277
 
Re: Ensure that multiline examples are correctly parsed

It's possible the issue here is in the docs tooling rather than in Strings. I'll investigate this as far as I can, but I may wind up looking for help on it.

Jean Bond (JIRA)

unread,
Aug 12, 2019, 8:19:03 PM8/12/19
to puppe...@googlegroups.com
Jean Bond updated an issue
Change By: Jean Bond
Comment:
The spacing on the above example has been fixed, but still has issues. I also found an issue with this line in functions:

For example, in the `break` function (starting at line 1):

{code}

# Breaks an innermost iteration as if it encountered an end of input.
# This function does not return to the caller.
#
# The signal produced to stop the iteration bubbles up through
# the call stack until either terminating the innermost iteration or
# raising an error if the end of the call stack is reached.
#
# The break() function does not accept an argument.
#
# @example Using `break`
#
# ```puppet
# $data = [1,2,3]
# notice $data.map |$x| { if $x == 3 { break() } $x*10 }
# ```
#
# Would notice the value `[10, 20]`
{code}


renders in generated docs output as

{code}

Breaks an innermost iteration as if it encountered an end of input.
This function does not return to the caller.

The signal produced to stop the iteration bubbles up through
the call stack until either terminating the innermost iteration or
raising an error if the end of the call stack is reached.

The break() function does not accept an argument.

```puppet
$data = [1,2,3]
notice $data.map |$x| { if $x == 3 { break() } $x*10 }
```

Would notice the value `[10, 20]`
{code}

Jean Bond (JIRA)

unread,
Aug 12, 2019, 8:20:03 PM8/12/19
to puppe...@googlegroups.com

Jean Bond (JIRA)

unread,
Aug 30, 2019, 5:17:02 PM8/30/19
to puppe...@googlegroups.com

Jean Bond (JIRA)

unread,
Aug 30, 2019, 5:18:03 PM8/30/19
to puppe...@googlegroups.com
Jean Bond commented on Bug PDOC-277
 
Re: Ensure that multiline examples are correctly parsed

Per 30 Aug 2019 meeting with Kris Bosland, this looks like an issue that might exist in the Docs' ERB template, not in Strings.

Reply all
Reply to author
Forward
0 new messages