Rdoc + yard

ruby-talk
1

Hi,

RDOC is the de facto documentation system for ruby core and stdlib.
YARD is being used over RDOC for the vast majority of the gems.

YARD also runs RDOC documentation.
That is a plus.
If we write our documentation in RDOC we can get the two worlds.
That approach makes sense to me.
RDOC can also be used with markdown.

RDOC documentation is to basic and as I can see the better way to make it
work would be by looking at current developed gems that already implement
their documentation with this philosophy in mind:
* RDOC with markdown as primary source
* RDOC + YARD generated documentation

Does someone happens to know some of these gems that I could use as a
reference?

Thanks,

Daniel

2

What to call this? Unsubstantiated? Hyperbole? FUD?

You pick.

···

On Jan 18, 2017, at 02:16, Daniel Ferreira <subtileos@gmail.com> wrote:

YARD is being used over RDOC for the vast majority of the gems.

3

> What to call this? Unsubstantiated? Hyperbole? FUD?

Sorry my bad English Ryan.

What I meant was:

YARD is being used as a replacement of RDOC for most of the gems.

Is it clearer now?

Thanks,

Daniel

4

YARD is, by design, broken. I have a fair amount of documentation where I
do something like:

```

···

##
# :attr_accessor: foo
#
# blah blah blah

##
attr_reader :foo

def foo=(v) # :nodoc:
  …
end
```

I do this because Rdoc actually has the ability to document virtual
attributes (the `:attr_accessor: foo` directive) and I don’t want to
document the `foo` and `foo=` separately. In their *wisdom*, the developers
of YARD have decided that people who use `:nodoc:` don’t really mean it,
and even if they do mean it, they don’t want them to mean it because it’s
not used appropriately.

So, no, I do not and will never use YARD as a replacement for Rdoc, because
it does the unforgivable: it thinks it knows better than I do. I have to do
some additional work, but I will also be changing all of the links I
provide to `rdoc.info` for my gems to links where I have generated the
documentation I expect.

-a

On Wed, Jan 18, 2017 at 5:16 AM, Daniel Ferreira <subtileos@gmail.com> wrote:

Hi,

RDOC is the de facto documentation system for ruby core and stdlib.
YARD is being used over RDOC for the vast majority of the gems.

YARD also runs RDOC documentation.
That is a plus.
If we write our documentation in RDOC we can get the two worlds.
That approach makes sense to me.
RDOC can also be used with markdown.

RDOC documentation is to basic and as I can see the better way to make it
work would be by looking at current developed gems that already implement
their documentation with this philosophy in mind:
* RDOC with markdown as primary source
* RDOC + YARD generated documentation

Does someone happens to know some of these gems that I could use as a
reference?

Thanks,

Daniel

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

--
Austin Ziegler • halostatue@gmail.com • austin@halostatue.ca
http://www.halostatue.ca/ • http://twitter.com/halostatue

5

Your English is fine. It's your numbers/proof that is lacking.

···

On Jan 18, 2017, at 04:50, Daniel Ferreira <subtileos@gmail.com> wrote:

Sorry my bad English Ryan.

What I meant was:

YARD is being used as a replacement of RDOC for most of the gems.

6

Currently I have everything setup and I can successfully generate RDOC and
YARD documentation from the same RDOC(markdown) code base.
I facing a problem though:
I'm currently struggling to get in yardoc the same links as I do for the
RDOC generated documentation.

When I use a reference to another class using

···

~~~
##
# See ::Foo::Bar

class Foo::Baz
end
~~~

In RDOC it generates the proper link but in YARD the link doesn't generate.
Any idea?

Thanks,

Daniel

7

Ok Ryan. I can give you that. I know your gems use pure RDOC by the way.
And I'm making use of hoe to generate and manage my own gems so I thank you
for that and would like you to know that I have a lot of respect for your
work extended to you as a person. This being said:

I should have added: "...from my experience..."

Thanks,

Daniel

8

I do this because Rdoc actually has the ability to document virtual attributes (the `:attr_accessor: foo` directive) and I don’t want to document the `foo` and `foo=` separately. In their *wisdom*, the developers of YARD have decided that people who use `:nodoc:` don’t really mean it, and even if they do mean it, they don’t want them to mean it because it’s not used appropriately.

Doesn't `!@visibility private` work?

Click here to view Company Information and Confidentiality Notice.<http://www.jameshall.co.uk/index.php/small-print/email-disclaimer&gt;

9

Hi,

I'm not being able to get the code highlight on the doc blocks.

e.g.

···

~~~
##
# Create default object:
#
# Class FooBar
# def default_type
# Baz
# end
# end
#
# FooBar.default_type
# # => Baz

def create
end
~~~

It all comes white but the source code is highlighted.
Any idea?

Thanks,
Daniel

10

Maybe, if you want to use YARD attributes. I don’t, because I don’t believe
that YARD offers any value over Rdoc itself. The point is that these items
are *not* private, I am documenting them differently than the code actually
is written. The objects in question do not have `foo` and `foo=` methods,
they have a writeable `foo` attribute, as an example. I could also,
theoretically, write YARD plug-ins to handle this. But I won’t, because
then I’d need to distribute those plug-ins for my gems to use, and it
wouldn’t at all help for sites like rdoc.info.

YARD is a bit like Rubocop’s default settings: mostly wrong. It has a
particular opinion expressed that doesn’t match particularly usable
documentation patterns, and that opinion is expressed through a misguided
sense of purity that actively makes good documentation worse because of
this particular opinion on documentation.

IMO, YARD is *not* a good Ruby documentation tool. It actively ignores
meaningful instructions provided by documenters and wants you to do more
useless work. Use Rdoc. It parses C extension files, GNU style changelog
files, Markdown, RD, Ruby + standard Rdoc, and TomDoc (which IMO is a
better format than YARD, but I still don’t use it at this point).

Just use and learn Rdoc.

-a

···

On Thu, Jan 19, 2017 at 4:13 AM, Andy Jones <Andy.Jones@jameshall.co.uk> wrote:

>>>>>>>>
I do this because Rdoc actually has the ability to document virtual
attributes (the `:attr_accessor: foo` directive) and I don’t want to
document the `foo` and `foo=` separately. In their *wisdom*, the developers
of YARD have decided that people who use `:nodoc:` don’t really mean it,
and even if they do mean it, they don’t want them to mean it because it’s
not used appropriately.
<<<<<<<<

Doesn't `!@visibility private` work?

Click here to view Company Information and Confidentiality Notice.<
http://www.jameshall.co.uk/index.php/small-print/email-disclaimer&gt;

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

--
Austin Ziegler • halostatue@gmail.com • austin@halostatue.ca
http://www.halostatue.ca/ • http://twitter.com/halostatue

11

RDOC can create links to other modules and/or class methods like:

···

~~~
class Foo
  def bar
  end

  def self.baz
  end
end

module Qux
  def self.quxqux
  end
end

##
# Delegator

class FooBar
  ##
  # Delegates to ::Foo#bar
  def bar
     Foo.new().bar
  end

  ##
  # Delegates to ::Foo::bar
  def baz
     Foo.baz
  end

  ##
  # Delegates to ::Qux::quxqux
  def qux
     Qux.quxqux
  end
end
~~~

All this works but I'm not being able to make it work for this situation:

~~~
module Qux
  ##
  # Abstract method

  def quxqux
     raise NotImplementedError
  end
end

class QuxBar
  include Qux

  ##
  # Abstract method override
  #
  # See Qux#quxqux
  def qux
     puts "Say qux"
  end
end
~~~

I know the method is not an instance method so I wonder what will be the
syntax to do this or if it is even possible.
Didn't see any examples and `rdoc/markup.rb` doesn't seem to mention this
situation.

Is this an existing feature?
If true
   What is the right syntax?
else
  Should it be a feature?
end

Thanks,

Daniel

12

I'm using the default darkfish template.

13

Hello, you need to write 'class', not 'Class' in doc block:

···

##
# Create default object:
#
# class FooBar
# def default_type
# Baz
# end
# end
#
# FooBar.default_type
# # => Baz

On Wed, Jan 18, 2017 at 6:14 PM, Daniel Ferreira <subtileos@gmail.com> wrote:

Hi,

I'm not being able to get the code highlight on the doc blocks.

e.g.

~~~
##
# Create default object:
#
# Class FooBar
# def default_type
# Baz
# end
# end
#
# FooBar.default_type
# # => Baz

def create
end
~~~

It all comes white but the source code is highlighted.
Any idea?

Thanks,
Daniel

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

--
Best wishes, Artem

14

Neglect my previous reply.
It was a typo. :slight_smile: (lets smile so that tears will not fall!)

15

Hi Austin,

I'm totally with you on this.
It is a shame ruby community is recommending and adopting YARD at such
large scale.
The only reason being the layout of the documentation in my opinion because
nowadays RDOC is very complete.
I'm using markdown in order to use the same markup everywhere as much as
possible and it seems RDOC is holding just fine.

Is there anyway of not displaying a public method in the documentation.

In this particular case I would like to mute `Module#included?` from the
`Foo` module documentation.
Tried using `:nodoc` but it doesn't seem to work.

Thanks,

Daniel

16

IMO, YARD is *not* a good Ruby documentation tool. It actively ignores meaningful instructions provided by documenters and wants you to do more useless work. Use Rdoc. It parses C extension files, GNU style changelog files, Markdown, RD, Ruby + standard Rdoc, and TomDoc (which IMO is a better format than YARD, but I still don’t use it at this point).

I don't have such a negative opinion of it, but I still prefer rdoc over yard because:

* One less dependency.

* I use ri extensively (weird I know) and Yard is not compatible (and yri does not read rdoc properly).

Click here to view Company Information and Confidentiality Notice.<http://www.jameshall.co.uk/index.php/small-print/email-disclaimer&gt;

17

Obviously. :slight_smile:

18

The error that was cancelling the highlight on the code blocks was this
thing:

···

~~~
# ::create
~~~

Just had to replace it by:

~~~
# FooBar.create
~~~

and the code block highlight is back again.

Is this a bug?

Thanks,

Daniel

19

All looking good now except the aforementioned link.

Anyone interested in a Guide for this setup?

I will use this setup pretty soon in the open source I will create for
OpenArtists.Org website.

It will be under: github/OpenArtists organisation.

I'm thinking in using Sinatra and Opal.

Thanks,

Daniel

20

The directive is `:nodoc:`, e.g.:

class Bar
  def foo #:nodoc:
    …
  end
end
···

On Thu, Jan 19, 2017 at 12:05 PM, Daniel Ferreira <subtileos@gmail.com> wrote:

Hi Austin,

I'm totally with you on this.
It is a shame ruby community is recommending and adopting YARD at such
large scale.
The only reason being the layout of the documentation in my opinion
because nowadays RDOC is very complete.
I'm using markdown in order to use the same markup everywhere as much as
possible and it seems RDOC is holding just fine.

Is there anyway of not displaying a public method in the documentation.

In this particular case I would like to mute `Module#included?` from the
`Foo` module documentation.
Tried using `:nodoc` but it doesn't seem to work.

Thanks,

Daniel

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

--
Austin Ziegler • halostatue@gmail.com • austin@halostatue.ca
http://www.halostatue.ca/ • http://twitter.com/halostatue