rdoc markup question

Discussion in 'Ruby' started by Gary Wright, Apr 30, 2007.

  1. Gary Wright

    Gary Wright Guest

    Is there a way to disable rdoc's automatic cross referencing of method
    names? I've got a method named 'null' but I don't want every instance
    of the word 'null' in the comments to be hyperlinked to the method
    definition. I tried writing '\null' or 'n\ull' but then the backslash
    shows up in the comments.

    Similarly I also found that when I have XML strings in the comments
    I can either use "\<!-- comment -->" and have the \ show up in the
    comments
    or have "<!-- comment -->" and have the rdoc parser die on me.

    Any suggestions?


    Gary Wright
    Gary Wright, Apr 30, 2007
    #1
    1. Advertising

  2. On Apr 29, 8:52 pm, Gary Wright <> wrote:
    > Is there a way to disable rdoc's automatic cross referencing of method
    > names? I've got a method named 'null' but I don't want every instance
    > of the word 'null' in the comments to be hyperlinked to the method
    > definition. I tried writing '\null' or 'n\ull' but then the backslash
    > shows up in the comments.


    Nope. I brought this up at
    http://groups.google.com/group/ruby...6b1c907f17/82b5df7ee399b70d?#82b5df7ee399b70d

    I find it annoying, too.

    > Similarly I also found that when I have XML strings in the comments
    > I can either use "\<!-- comment -->" and have the \ show up in the
    > comments
    > or have "<!-- comment -->" and have the rdoc parser die on me.


    Sounds like a bug to me. Please report it.

    Regards,

    Dan
    Daniel Berger, Apr 30, 2007
    #2
    1. Advertising

  3. Gary Wright

    Gary Wright Guest

    On Apr 30, 2007, at 12:00 AM, Daniel Berger wrote:

    > On Apr 29, 8:52 pm, Gary Wright <> wrote:
    >> Is there a way to disable rdoc's automatic cross referencing of
    >> method
    >> names? I've got a method named 'null' but I don't want every
    >> instance
    >> of the word 'null' in the comments to be hyperlinked to the method
    >> definition. I tried writing '\null' or 'n\ull' but then the
    >> backslash
    >> shows up in the comments.

    >
    > Nope. I brought this up at
    > http://groups.google.com/group/ruby-talk-google/browse_frm/thread/
    > 9379ed6b1c907f17/82b5df7ee399b70d?#82b5df7ee399b70d
    >
    > I find it annoying, too.


    I read that thread. I think the default heuristic is ok. In the
    thread you suggested an explicit syntax to trigger the cross-reference.
    I'd suggest an explicit syntax to disable the cross-reference.

    I could of course come up with a patch but even if adopted it would
    take a while to propagate through the Ruby ecosystem. I was hoping
    there was a trick or hack of some sort.

    I see that this issue is actually entered into the the tracker for rdoc
    as issue 9316. There are quite a few unresolved issues in the list...


    Gary Wright
    Gary Wright, Apr 30, 2007
    #3
  4. Gary Wright

    Gary Wright Guest

    On Apr 30, 2007, at 12:00 AM, Daniel Berger wrote:

    > On Apr 29, 8:52 pm, Gary Wright <> wrote:
    >> Similarly I also found that when I have XML strings in the comments
    >> I can either use "\<!-- comment -->" and have the \ show up in the
    >> comments
    >> or have "<!-- comment -->" and have the rdoc parser die on me.

    >
    > Sounds like a bug to me. Please report it.


    I've entered this into the tracker for rdoc (#10474):

    In markup/simple_markup/inline.rb:

    add_special(/<!--(.*?)-->/, :COMMENT)

    marks an XML comment to be given special handling but the method
    handle_special_COMMENT
    is never defined. This causes an unhandled exception when the HTML
    generator runs:

    /opt/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:230:in
    `convert_special': Unhandled special: Special: type=17,
    text="<!-- foo -->" (RuntimeError)

    I'm not sure if the intent was to insert the XML comment into the
    generated XHTML or to
    escape the comment so that it appeared as readable text.

    The following code illustrates the problem:

    class A
    # The line below is OK because it is processed as a <pre> block:
    # <!-- comment -->
    def method1
    end

    # The line below is OK because it is protected by the \.
    # \<!-- comment-->
    def method2
    end


    # The line below is OK because it doesn't match any markup patterns
    # <foo>some text</foo>
    def method4
    end

    # The line below is not OK because the handler for the :COMMENT
    pattern
    # is not defined:
    # <!-- comment-->
    def method3
    end

    end



    Gary Wright
    Gary Wright, Apr 30, 2007
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Stefan Lang
    Replies:
    2
    Views:
    113
    Stefan Lang
    Dec 31, 2004
  2. Peter Marsh

    RDoc markup

    Peter Marsh, Jun 10, 2007, in forum: Ruby
    Replies:
    2
    Views:
    103
    Eric Hodel
    Jun 12, 2007
  3. Jesper Rønn-Jensen
    Replies:
    4
    Views:
    137
    Joel VanderWerf
    Feb 22, 2008
  4. Serg Koren

    Proper way to RDoc markup?

    Serg Koren, Feb 15, 2008, in forum: Ruby
    Replies:
    11
    Views:
    229
    Tony Strauss
    Sep 27, 2008
  5. Intransition

    Better RDoc Inline Markup

    Intransition, Sep 3, 2009, in forum: Ruby
    Replies:
    11
    Views:
    186
    trans
    Sep 5, 2009
Loading...

Share This Page