Replacing RDoc: what do you want to see?

Discussion in 'Ruby' started by ES, Aug 27, 2005.

  1. ES

    ES Guest

    I am thinking of starting something up to entirely
    replace (not fix) RDoc, so I need some input.

    There is only so much data to be gathered from the
    source code and RDoc is fairly good at that. What
    it is not good at is keeping things simple while
    producing a usable data structure. Those are things
    that would be automatically corrected. Are there
    any other 'mechanical' things that need to be fixed?

    The main task would probably be to revise the format
    of the documentation itself: allow 'keywords' for a
    return value, parameters, examples and so on to build
    more meaningful and consistent documentation while
    keeping the format as natural as possible. Any good
    requests for this part?

    The third thing is migration... should probably allow
    converting to any new documentation format by just
    running a script or then support the old format out
    of the box.

    So, make a list.

    E
    --
    template<typename duck>
    void quack(duck& d) { d.quack(); }
     
    ES, Aug 27, 2005
    #1
    1. Advertising

  2. ES

    James Britt Guest

    ES wrote:
    > I am thinking of starting something up to entirely
    > replace (not fix) RDoc, so I need some input.


    Have you considered discussion this in the ruby-doc mailing list? There
    have been assorted discussion there on rj, ri.next, and so on.

    You can find info about the list at

    http://www.ruby-doc.org


    As for feature requests, the ability to rdoc/ri new files while not
    risking the munging of existing rdoc/ri data sets.

    (Incidentally, are you planning on replacing ri in the process? It
    seems that an ri alternative would be a natural thing add, even if you
    are not targeting that.)


    James

    --

    http://www.ruby-doc.org - The Ruby Documentation Site
    http://www.rubyxml.com - News, Articles, and Listings for Ruby & XML
    http://www.rubystuff.com - The Ruby Store for Ruby Stuff
    http://www.jamesbritt.com - Playing with Better Toys
     
    James Britt, Aug 27, 2005
    #2
    1. Advertising

  3. On 8/27/05, ES <> wrote:
    > I am thinking of starting something up to entirely
    > replace (not fix) RDoc, so I need some input.


    Honestly, I don't want to see RDoc replaced. I *do* want to see it
    fixed. If this means that you create an implementation that replaces
    the current one while keeping the same interface and it's of a
    high-enough quality that Matz accepts it into the core, then more
    power to you. However, if it isn't going to make it into the core,
    then I think that it's a bit of a distraction and you'd be better off
    working with the RDoc maintainers (and possibly seeing about becoming
    one yourself) to fix what's wrong with RDoc.

    -austin
    --=20
    Austin Ziegler *
    * Alternate:
     
    Austin Ziegler, Aug 27, 2005
    #3
  4. ES

    James Britt Guest

    Austin Ziegler wrote:
    > On 8/27/05, ES <> wrote:
    >
    >>I am thinking of starting something up to entirely
    >>replace (not fix) RDoc, so I need some input.

    >
    >
    > Honestly, I don't want to see RDoc replaced. I *do* want to see it
    > fixed. If this means that you create an implementation that replaces
    > the current one while keeping the same interface and it's of a
    > high-enough quality that Matz accepts it into the core, then more
    > power to you. However, if it isn't going to make it into the core,
    > then I think that it's a bit of a distraction and you'd be better off
    > working with the RDoc maintainers (and possibly seeing about becoming
    > one yourself) to fix what's wrong with RDoc.


    I don't entirely disagree with this, but I don't buy the "distraction"
    argument. If RDoc and "ES-doc" are destined for different paths, so be
    it. I'm happy to have alternatives for extraction useful information
    from source code. Choice is good.

    I've spent enough time trying different approaches to custom parsing the
    ri yml files, with unsatisfactory results, that I heartily encourage
    people to try their hand at rdoc alternatives and offer up what they find.



    James

    --

    http://www.ruby-doc.org - The Ruby Documentation Site
    http://www.rubyxml.com - News, Articles, and Listings for Ruby & XML
    http://www.rubystuff.com - The Ruby Store for Ruby Stuff
    http://www.jamesbritt.com - Playing with Better Toys
     
    James Britt, Aug 27, 2005
    #4
  5. ES

    Eric Hodel Guest

    On 27 Aug 2005, at 13:46, Austin Ziegler wrote:

    > On 8/27/05, ES <> wrote:
    >
    >> I am thinking of starting something up to entirely
    >> replace (not fix) RDoc, so I need some input.
    >>

    >
    > Honestly, I don't want to see RDoc replaced. I *do* want to see it
    > fixed. If this means that you create an implementation that replaces
    > the current one while keeping the same interface and it's of a
    > high-enough quality that Matz accepts it into the core, then more
    > power to you. However, if it isn't going to make it into the core,
    > then I think that it's a bit of a distraction and you'd be better off
    > working with the RDoc maintainers (and possibly seeing about becoming
    > one yourself) to fix what's wrong with RDoc.


    If RDoc is broken, people should file bugs so that us maintainers can
    fix things.

    http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse

    --
    Eric Hodel - - http://segment7.net
    FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04
     
    Eric Hodel, Aug 27, 2005
    #5
  6. On 8/27/05, Eric Hodel <> wrote:
    > If RDoc is broken, people should file bugs so that us maintainers can
    > fix things.


    Agreed. There are some things that I'd like to see done, but nothing
    that bothers me *quite* enough to file anything. Lothar seems to think
    that there are bigger problems, but also seems uninterested in filing
    bug reports. However, I think that there's a definite suggestion that
    the complexity of RDoc might be higher than perhaps it should be, at
    least the intermediate forms. The biggest problem that I've seen with
    ri -- and again, I haven't checked yet on the bug tracker -- is its
    inability to cleanly merge modifications.

    -austin
    --=20
    Austin Ziegler *
    * Alternate:
     
    Austin Ziegler, Aug 28, 2005
    #6
    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. Flip
    Replies:
    3
    Views:
    978
    Tony Morris
    Feb 9, 2004
  2. Brad Allen
    Replies:
    0
    Views:
    301
    Brad Allen
    Sep 30, 2006
  3. Mike Barnard
    Replies:
    10
    Views:
    607
    Chris F.A. Johnson
    Mar 19, 2008
  4. Harlan Messinger

    The controls Visual Studio doesn't want you to see

    Harlan Messinger, Apr 4, 2010, in forum: ASP .Net
    Replies:
    1
    Views:
    323
    Harlan Messinger
    Apr 6, 2010
  5. Daniel Nugent
    Replies:
    16
    Views:
    190
    Daniel Nugent
    Jun 29, 2005
Loading...

Share This Page