yardoc --asset behaves differently on first and subsequent calls.

[dominikh]

When first executing yardoc --asset foo:bar, where foo is a directory, foo correctly gets copied to doc/bar. But on subsequent calls, it gets copied to doc/bar/bar. The following shell session should clarify it:

>>> tree
.
├── docs
│   └── images
│       └── foo.png
└── lib

3 directories, 1 file

>>> yardoc --asset docs/images:images
>>> tree
.
├── doc
[snip]
│   ├── images
│   │   └── foo.png
├── docs
│   └── images
│       └── foo.png
└── lib

7 directories, 15 files

>>> yardoc --asset docs/images:images
>>> tree
.
├── doc
[snip]
│   ├── images
│   │   ├── foo.png
│   │   └── images
│   │       └── foo.png
[snip]
├── docs
│   └── images
│       └── foo.png
└── lib

8 directories, 16 files

>>> yardoc --asset docs/images:images 
>>> tree 
.
├── doc
[snip]
│   ├── images
│   │   ├── foo.png
│   │   └── images
│   │       └── foo.png
[snip]
├── docs
│   └── images
│       └── foo.png
└── lib

8 directories, 16 files

[lsegal]

This is actually not an error in YARD but a reality of copying directories on a filesystem. The same problem happens in the shell:

$ mkdir foo
$ cp -R foo bar
$ tree bar
bar

0 directories, 0 files
$ cp -R foo bar
$ tree bar
bar
`-- foo

1 directory, 0 files

Usually the way you work around this is by adding a / suffix to the src, but we use FileUtils to perform cp's, and it doesn't seem to like that-- but according to the docs, the recommended way is to use a /. suffix:

If you want to copy all contents of a directory instead of the
directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
use following code.
FileUtils.cp_r 'src/.', 'dest' # cp_r('src', 'dest') makes src/dest,
# but this doesn't.

[lsegal]

I guess the question is, should we just force this when src is a directory, or is there a legitimate use of the existing behaviour?

[dominikh]

I personally would just force it, with the following reason: The TO in FROM:TO acts as a name, not a target. An alternative would be to do something similar to rsync: If the destination has no slash, overwrite, if it has a slash, copy into it.

Edit: Okay, I just saw your note regarding FileUtils and a trailing slash on the source. Considering that that seems to be broken and my rsyncesque suggestion would be a third way... I recommend just forcing it.

[FranklinYu]

Is the --asset option documented anywhere but in yard doc --help? I was looking for an example of usage.