Rdoc + yard

ruby-talk
21

I'm happier for sure. :slight_smile:

It is a lesson for the future.
DDD (Documentation Driven Development) may bring with it some specificities.
Not much to worry about though.

Thanks,
Daniel

22

What about doing: `private :included?`. It seems it is not breaking the
code.

Would this be a `Best Practice` to put in place?

Thanks,
Daniel

23

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

IMO YARD puts an extra layer of abstraction that doesn't bring any
advantage in terms of markup.
It forces a developer to know another documentation system when everything
is just fine with RDOC.

When I read a source code with documentation written in RDOC the reading is
much easier to the eyes.
And for me as a developer it is much easier to write as well because I can
almost freely express my reasoning without further markup barriers.

Writing documentation for me it is part of the design process and it is
very important in that process to not be distracted by those little extra
things that are totally avoidable.

Why force your developers to learn such a thing.

Ruby developers should be exposed to ruby core.
It is with the exposure to ruby core that the developer can aspire to
become a ruby master.

That is why I advocate also the use and development of internal gems over
the use of community ones.

Although there are exceptions like Austin's `diff-lcs` another gem I've
been using a lot. Thanks Austin. Awesome work. But there are much more.

The rule is not to say we don't want to work with the community but instead
to promote self awareness and development independence.

Working closer to the core can only bring good things at the longer term.

My experience tells me that.

Thanks,
Daniel

24 
class Bar
   def foo #:nodoc:
     ā€¦
   end
end

I'll try that tomorrow then. Thanks Austin.

By the way: why `:call-seq:` doesn't work under markdown? Is it just me?

Thanks,

Daniel

25

Hi!

As weā€™ve got this RDOC + YARD thread I was wondering how to 'bestā€˜ document attributes in Ruby with RDOC.

Hereā€™s an example of what Iā€™m up to:

Ā·Ā·Ā·

~~~
# Attribute 1 does this and attribute 2 does that
attr_accessor :attr1, :attr2
ā€¦
~~~

This leads to the comment being repeated twice, once for each attribute:

~~~RDOC:
Attributes

attr1[RW]
Attribute 1 does this and attribute 2 does that

attr2[RW]
Attribute 1 does this and attribute 2 does that
~~~

Not really the thing Iā€™m looking forā€¦putting each attribute onto its own line with its own comment looks better in RDOC but kind of inflates the code from my point of view, esp. if there are a couple of attributes (which is of course a discussion of its own;):

~~~
# Attribute 1 does this
attr_accessor :attr1

# Attribute 2 does that
:attr2
ā€¦
~~~

~~~RDOC:
# Attribute 1 does this
attr_accessor :attr1
    
# Attribute 2 does that
attr_accessor :attr2
~~~

How do you guys handle this generally?

Many thanks!

Cheers,
Michael

Am 19.01.2017 um 19:21 schrieb Austin Ziegler <halostatue@gmail.com>:

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

class Bar
  def foo #:nodoc:
    ā€¦
  end
end

[ā€¦]

Mit freundlichem GruƟ
Michael Schwarze

26

No idea. I only use native rdoc in my code comments, and Markdown for
supplementary files.

-a

Ā·Ā·Ā·

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

> ```ruby
> class Bar
> def foo #:nodoc:
> ā€¦
> end
> end
> ```

I'll try that tomorrow then. Thanks Austin.

By the way: why `:call-seq:` doesn't work under markdown? Is it just me?

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

27

Hi Michael,

If you're looking forward to properly document your code my first advice is
for you to not be worried about "inflated codes"

Good documentation implies inflated code.

What is the purpose of commenting two methods on the same line?

It is confusing for the reader. Not clear at all.

Use `:nodoc:` for the attributes you do not want to document and treat all
the other attributes as methods on their own right.

An entry point in the interface deserves exposure and relevance.

That is also the reason why I advocate the use of access modifiers for each
method and attribute setting quite often attributes as private or protected.

Look at rails source code. You will get an idea on how to do it.

100% doc coverage should also be a goal.

Thanks,
Daniel

28

I would like YARD to display both source code RDOC and markdown docs files
seamlessly.

The problem here is that it is very hard to sell darkfish RDOC template to
the department.
They only bought my proposal because I told them I would deliver YARDOC for
free, so that is a must but I would love to be able to implement the
pattern you are using.

Is it possible to achieve the same thing with YARD.

Another thing would be to get a RDOC template that could rival with
YARDOC's one.

Anyone is aware of good templates in that regard?

Thanks,
Daniel

Ā·Ā·Ā·

On Thu, 19 Jan 2017 at 19:24, Austin Ziegler <halostatue@gmail.com> wrote:

No idea. I only use native rdoc in my code comments, and Markdown for
supplementary files.

Interesting. How does it work then? Maybe I will start to do the same. But

29

IMO YARD puts an extra layer of abstraction that doesn't bring any advantage in terms of markup.
It forces a developer to know another documentation system when everything is just fine with RDOC.

I actually think that the web pages YARD generates are a lot better. And (although I suppose it's not very Ruby-esque) I like that it wants you to document the expected nature of the parameters and the return value for each method.

Documentation is the thing that we do worst in Ruby, I think. So it's a shame that it doesn't work well for me. Ah well.

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

30

Theyā€™re bikeshedding on styling but ignoring that YARD is a broken tool? Thatā€™s odd...

Ā·Ā·Ā·

On Jan 19, 2017, 12:38 -0800, Daniel Ferreira <subtileos@gmail.com>, wrote:

The problem here is that it is very hard to sell darkfish RDOC template to the department.

31

Hi Ryan,

People seem to have inclinations for "oddicity" type of behaviours.
When you see them using rspec over minitest...

It is a cultural thing: rails, rspec, cucumber, capybara, capistrano,
rubocop.

Which ones do not use YARD?

Rails perhaps? Capistrano doesn't even have documentation.

That is the stack and YARD rules.

Plus lots of people advocate that code should speak for itself. I don't
agree with that at all.
Architecture should rule.
And architecture without documentation is volatile in my opinion.
Agile should not be chaos.
I've experienced it. I know what I'm talking about.
And in the end it will end up as ruby fault because they don't know the
language.
Ruby demands more then just OOP basic knowledge.
Rails makes everything ready to be consumed and they think there is no
point in documentation.
Big controllers and giant models.
Was it just me?

Trying to make a statement and approach ruby development as I think it
should be done but when you work in an organisation you have to negotiate
wills.

And then always the pressure of delivery.

Lets see how it will go.
But yes. We developers are constrained by the environment.
I always have been.

Thanks,
Daniel

32

Hi Andy,

Everything but the default template. I believe I've mentioned it already
and that is the reason I'm using YARD in top of RDOC.

Thanks,
Daniel

33

I agree that Darkfish is a pretty unreadable RDoc template. Luckily,
there is an official alternative with hanna-nouveau[1], which I use to
document my ruby-xz gem if you want to take a look at an example using
it[2].

Greetings
Marvin

[1]: GitHub - jeremyevans/hanna: RDoc generator designed with simplicity, beauty and ease of browsing in mind
[2]: http://quintus.github.io/ruby-xz/

Ā·Ā·Ā·

On Thu, Jan 19, 2017 at 08:38:15PM +0000, Daniel Ferreira wrote:

The problem here is that it is very hard to sell darkfish RDOC template to
the department.

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

34

I vehemently advocate that good code should speak for itself.

That doesn't mean that a library should not have a good
documentation of it's public interface, but rather that code
should be written in such a way that it's not necessary to
explain obscure code constructs in comments.

That's at least how I take it.

Good code should speak for itself _and_ a library should have
good documentation, with examples etc. (I use ri all the time.)

Regards,
Marcus

Ā·Ā·Ā·

Am 19.01.2017 um 23:37 schrieb Daniel Ferreira:

Plus lots of people advocate that code should speak for itself.
I don't agree with that at all.
Architecture should rule.

--
GitHub: stomar (Marcus Stollsteimer) Ā· GitHub
PGP: 0x6B3A101A

35

The directive is `:nodoc:`

Worked like a charm. Thanks. Daniel

36

Thanks Marvin, that is true. I've played with it during yesterday. Takes
darkfish's bug with long class names not appearing completely in the left
column since it uses frames for that.
I little bit the old school look and feel of doxygen.
Let's see how it goes.

In the future I believe the community should invest some type in developing
a modern responsive template to be used across all devices.

With the aim of allowing easy customisation like rebranding.

Count with me on that.

Cheers,

Daniel

37

Hi Marcus,

I totally agree with you.
I didn't express my thought as I should.
Many thanks for your contribution to the discussion.

What I was trying to say is that when you have undocumented code and tiny
classes you can open a file, read the code and know what is there.
I see this a lot.

So you have public methods in the top, then protected methods and then
private methods.

The attributes will all be in one line and all is clean and beautifull as
it should be because ruby is beautiful.

You did an effort to give the proper names to classes, methods and
variables and for a developer everything is clear.

The code speaks for itself.
No documentation is needed.

The public interface is clearly defined and the examples on how to use each
one of the method is intuitive.

All good? No. Not in my opinion.

Unless that class is totally isolated from anything else there will always
be a time where if you don't specifically state it in the documentation a
functionality will be lost or ignored. Why? Because code gets complex very
quickly.

What was a tiny class it is not anymore.
Functionalities are added.
The 50 lines are now 150 and without documentation.

What was one class it is now a collection of modules and classes. (This is
exactly what is happening to the code I'm writing at the moment)

If documentation is not in place a developer will have an hard time trying
to grasp the logic behind the architecture setup.

Then how to look into a class and understand the interface?

The documentation should be the first place to go.

The documentation should be the first place where a developer should go to
learn how to use a library. What methods are available. Why the
architecture was designed in a certain way.

The second place should be the acceptance tests. Where the API examples
should be complete and crystal clear.

And she should only need to go to the source code in three situations:
1. To learn how to code properly.
2. To work on the code base.
3. To improve even more the documentation.

Every time a new developer finds it hard to understand the all thing by
reading through the documentation then it is time to take the chance and
put some effort in understanding what is lacking. What needs to be
improved. Zero assumptions should be the rule. Any required background
should have a link or somehow be mentioned.
Documentation for me should be like a school book where the developer is
teaching his way through the code.

With this in mind, code as in "the source code file" it is not readable
anymore. It gets "inflated". The reader doesn't no anymore by looking at a
method what is it's visibility. Is it public or private? Maybe protected?
Shit I need to find out. That is why in my classes every method
specifically state its own access modifier. All except the initialize
method that stays at the top of the class.

Until further notice, I believe I'm the only one in the world doing it.

So there you go, a little bit more insight on my reasoning around style and
best practices,

In ruby, conventions are also a must but that I leave it for another time.

Thanks,

Daniel

38

Good news: `call-seq` is working. My bad again. It obviously needs to be
used in top of the method. Trying to use it in top of the class. :slight_smile:

39

Hi,

I'm having an hard time trying to create a link into a constant from
outside its class.

Does anyone has some examples?

Also `hanna_nouveau` displays the constants value on the documentation.
`darkfish` and `olddoc` does not. Is it the expected behaviour?

Thanks,

Daniel