Can't have a list in @param?

[Steve]

I've looked around and can't find anyone else having this issue, so I
must just be doing something wrong. When I try to include a list when
defining a parameter, it just outputs in the documentation as a
regular sentence. I've tried various indenting, and list
indicators(-,*,+).

@param [Symbol, <Symbol>] key the projects to load
- :all - ...
- :active - ...
- :inactive - ...
- :project_key

[Loren Segal]

Steve wrote:
> ... When I try to include a list when

> defining a parameter, it just outputs in the documentation as a
> regular sentence.

Thanks for pointing this out. A change I just made in the tags API
(http://bit.ly/afTDiK) should resolve this issue for you. git pull and
rake install the master branch and let me know if you have problems.

- Loren

[Steve]

Closer, it gets the list in there, except it doesn't obey the markdown
rules for allowing multiple lines in an item. So this:

- some stuff
that breaks onto a new line
- More list action
on another line
- last item

renders as:

<ul>
<li>some stuff

</li>
</ul>

that breaks onto a new line

<ul>
<li>More list action

</li>

</ul>

on another line

<ul>
<li>last item

</li>
</ul>

Instead of:

<ul>
<li>some stuff
that breaks onto a new line</li>
<li>More list action
on another line</li>
<li>last item</li>
</ul>

Also, I don't know if this change is supposed to handle this(the
commit sort of sounded like it was, but I may have misunderstood),
line breaks are not being treated as new paragraphs inside of a tag.
New paragraphs are only made in the main description.

[Loren Segal]

Steve wrote:
> Closer, it gets the list in there, except it doesn't obey the markdown
> rules for allowing multiple lines in an item. So this:
>
>

Oops, I missed something in the refactoring. http://bit.ly/dxquQc should
deal with this issue

> Also, I don't know if this change is supposed to handle this(the
> commit sort of sounded like it was, but I may have misunderstood),
> line breaks are not being treated as new paragraphs inside of a tag.
> New paragraphs are only made in the main description.
>

You should be able to use two newlines for a new paragraph, see the
test: http://github.com/lsegal/yard/blob/master/spec/docstring_spec.rb#L172

tags[2].text.should == "and this\nis a new paragraph:\n\nright here."

Note the \n\n, this should be properly handled by a markup processor. Is
this not what you are getting? What is your tag text in this case?

- Loren

[Steve]

The list is all good now. The paragraph breaks are not happening
though. Here is what I have:

# @option options [Symbol] :on alias for +:of+ Here is the first
paragraph
# with some wrapping text.
#
# And now I would like a second one.

It just gives it all jammed together in one chunk:

Here is the first paragraph with some wrapping text. And now I would
like a second one.

[Loren Segal]

On 2010-03-21, at 1:00 AM, Steve wrote:
>
> The list is all good now. The paragraph breaks are not happening
> though. Here is what I have:
>
>

This actually had to do with the way tags were being printed and styled as "inline" text- the <p> tags were being removed so that they could sit side by side with the parameter/option name. The styling has been adjusted so that the p tags are no longer removed but the first p tag is displayed inline and the rest as block-- this should resolve the issue, though it might be a little more browser-sensitive.

- Loren

[Steve]

The paragraph breaks are all good now. There's a list styling issue
though. The first list item is missing its bullet. It looks like it's
picking up this style:

.inline :first-child {
display:inline;
}

changing it to .inline p:first-child seems to fix it, but I don't know
the extent of how the styles are used and if that would break
something else.

Annoying, but not the end of the world is that the nested lists get
hit with .tags ul, and so they all have list-style-type: square; Maybe
changing that to .tags>ul? Again, I don't know if this would have
other unintended consequences.

[Loren Segal]

Steve wrote:
> On Mar 21, 2:32 am, Loren Segal <lse...@soen.ca> wrote:
>
>> On 2010-03-21, at 1:00 AM, Steve wrote:
>>
>>
>>
>>
>>> The list is all good now. The paragraph breaks are not happening
>>> though. Here is what I have:
>>>
>> This actually had to do with the way tags were being printed and styled as "inline" text- the <p> tags were being removed so that they could sit side by side with the parameter/option name. The styling has been adjusted so that the p tags are no longer removed but the first p tag is displayed inline and the rest as block-- this should resolve the issue, though it might be a little more browser-sensitive.
>>
>
> The paragraph breaks are all good now. There's a list styling issue
> though. The first list item is missing its bullet. It looks like it's
> picking up this style:
>
>

<snip>

> changing it to .inline p:first-child seems to fix it, but I don't know
> the extent of how the styles are used and if that would break
> something else.
>

I think I'll switch it to the first <p> tag. I wouldn't want header tags
inlined either, so it really should just be for paragraphs.

- Loren

[keithr...@gmail.com]

Loren -

I'm having a similar problem.

I want to display a list of possible return values.  I can get it to render as a list, but the list renders before the param and return tag texts!

What am I doing wrong?  Here's the comment text:

  # Validates a message's DNSSEC information.
  #
  # @param message can be in any of the following formats: DNSRuby, DNSJava, binary string, byte array
  # @return one of the following possible values SecurityStatus class:
  # * UNCHECKED      0
  # * BOGUS          1
  # * INDETERMINATE  2
  # * INSECURE       3
  # * SECURE         4  (success)

Thanks,
Keith

[Loren Segal]

It looks like you might not be indenting those list items that are part of the return tag, which is necessary to associate text with a tag. See here for documentation on tag syntax: http://rubydoc.info/docs/yard/file/docs/Tags.md#Tag_Syntax

Regards,

Loren

--
 
---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.