Q: Are comment lines allowed in yardopts file ?

[DanRathbun]

Q: Are comment lines allowed in yardopts file ?

Thoroughly read the Guide and the yardopts help file and find no solution.

Starting a line with a # character does not seem to work.

This came up because I desire to do 2 things:

1. In testing, I want to temporarily switch "off" an option line without having to delete the line (or create a cloned file with a different name.)

2. I want to place an informational "reason" above some options to explain (to other users coming later) why I used the options the way I did. (To avoid someone coming along later and thinking they knew better and could change the options or consolidate them differently which would have a negative effect on the output.)

[lsegal]

Comments are not supported in .yardopts files. This would be an added feature that could be introduced as a PR, but is fairly low priority for this project given that you should be able to remove the line and use standard source control versioning tools (git etc) to keep track of what was temporarily disabled.

If you're really toggling switches in your options file that often, you may want to look into using -e to execute a YARD extension and add command line arguments dynamically, possibly via your ENV.

[DanRathbun]

... you should be able to remove the line and use standard source control versioning tools (git etc) to keep track of what was temporarily disabled.

I don't want it to be a version of my repo.

If you're really toggling switches in your options file that often, ...

Never used the word "often".

Basically it is usually that I want some options off whilst authoring and testing extra pages.

So this usually means making a backup copy of the "production" yardopts and making the temporary changes. OR ... have a set of specially named yardopts files and specifying which one to use as circumstances warrant, either via manually adding the switch to the command line or using a small batch command with yardoc commands in it.

Both of your suggestions would just complicate the situation. And neither would solve the desire to embed commentary into the file. Having a separate comments file has the disadvantage that people are always in a hurry and don't read such files.

Anyway, ... where is the code located that reads and processes the yardopts file ?

[lsegal]

I don't want it to be a version of my repo. ... Basically it is usually that I want some options off whilst authoring and testing extra pages.

It doesn't have to be a "version" (commit). Delete the line from the .yardopts, test your code, git checkout -- .yardopts to reset the file. Not sure why you would have to make any copies of files on disk. Your source control has the copy. My point is this is more of a source control management issue. If you're explicitly not going to retain those commented out lines in your repository history, I don't see why YARD needs to support this use case.

FWIW if you're making changes to your .yardopts in order to author / modify extra pages it kind of sounds like a misuse of the .yardopts file in general to comment anything out. I'm not sure I follow the use case for commenting out lines if the goal is authoring / testing extra pages. Can you describe how you modify the .yardopts file in an edit flow?

Anyway, ... where is the code located that reads and processes the yardopts file ?

https://github.com/lsegal/yard/blob/main/lib/yard/cli/yardopts_command.rb

[DanRathbun]

git checkout -- .yardopts to reset the file.

FYI, I am not working from a Git repo. And I really don't want to have to learn Git CLI. It's enough for me to use the GitHub Desktop and occasionally push to the few GitHub repos I have.

Can you describe how you modify the .yardopts file in an edit flow?

I actually no longer need to do this specifically in this project. I was commenting out two --asset options. But I no longer even need to copy these as those pages are generated now each time yardoc runs.

Listen, for me I've been commenting out unneeded options or commends since 1985 or so. It is fast, straightforward, easy and does not complicate the need by bringing in other processes (Git) etc. To me, it's not a weird idea. It takes 2 seconds. And I'm still rollin'.

I don't see why YARD needs to support this use case.

Well I suppose I can write my own plugin then.

The real use case as I had said was that I wish to embed comments within the file.

Thanks for the link to the YardoptsCommand class. It looks the yardopts() method might the place. If the file is read into an array of lines as in File.readlines then comment lines could be easily rejected. The reduced array then joined can have your shell_split called upon it.

My quick test shows this works to reject any lines beginning with a #...

lines = File.readlines(file).select {|line| line !~ /^#/ }

Afterward the yardopts() method can return ...

lines.join.shell_split

[DanRathbun]

So this morning I am running tests having backed up the original "yardopts_command.rb" file. Parsing the .yardopts containing multiple comment lines works fine with the method as:

      def yardopts(file = options_file)
        return [] unless use_yardopts_file
        lines = File.readlines(file).select {|line| line !~ /^\s*#/ }
        lines.join.shell_split
      rescue Errno::ENOENT
        []
      end

(I opted to allow whitespace in front of the #.)

---

In the original you were purposefully using a binary read for a simple text file. Is the binary read an important issue ?

Ie ...

# File 'lib/yard/core_ext/file.rb', line 66

def self.read_binary(file)
  File.open(file, 'rb', &:read)
end

---

@DanRathbun : Well I suppose I can write my own plugin then.

I just realized that if I use a plugin, I'll have to specify it's use on the command line as it would be too late as a line option in the .yardopts file as that file would already be loaded and choking on the comments lines.

EDIT: But there is a comment in yardopts_command.rb: parse_arguments() that says # Parse files and then command line arguments ... so I'm not sure a plugin would work at all.