Comments (5)
Hi,
YARD does not autolink class names. Everything is plain English unless otherwised marked up. You should use the {OBJECT} syntax to link a class method as code. The reason it stops at Test. is because the summary reads until the end of the first sentence (ending with a period)-- because this is all plaintext, the first sentence ends at "Test."-- You'd want {Test.test} if you need the method to be linked.
from yard.
Thanks for the explanation.
This difference seems like it could be a barrier to adoption for projects considering switching from rdoc to yard, however. Is there a possibility for a switch to enable the rdoc cross-referencing behavior?
from yard.
Hmm, when I try your suggestion, the summary ends up reading "Shortcut for {Test." It is linked correctly in the details.
from yard.
I don't think this would be a barrier to adoption. That would be like saying Textile's formatting could be a barrier to adoption to anyone using Markdown-- they're simply different markups. Frankly, I'd see the use of @param, @return and other tags a much bigger "barrier to entry" than having to add {} to the first instance of the class and method names in your docstrings.
That said, your report about {foo.bar} is right-- the CodeObjects::Base#summary
method needs to be beefed up to handle more complex sentence content.
Another thing I should point out is if you're looking to document an inter-namespace "shortcut" (or any other reference), you should really consider using a @see tag:
# @see Test.test def Test; end
from yard.
Hi Loren,
Let me explain why I think it might be a barrier. I came across yard after browsing through rdoc-generated documentation for a lot of different projects and thinking "there must be something better." And yard looks great -- semantic markup, support for DSLs, extensible tags, and key for existing projects which are already invested in rdoc: compatible syntax. "By default, YARD is compatible with the same RDoc syntax most Ruby developers are already familiar with." This means that we can switch from rdoc to yard without immediately having to rewrite all the existing markup, and then incrementally begin using yardoc-specific tags to improve the existing documentation. In this scenario, each incompatibility with rdoc is a barrier to switching. If I have a lot of documentation which is (mostly) correctly cross-referenced by rdoc, and switching to yard would result in those cross-references disappearing until I go back and explicitly mark them all up, that becomes a reason for me not to switch. Not insurmountable by any means, but it will be the point at which someone considering yardoc is likely to go from thinking "yard looks great, and I think I'll be able to start using it in my projects without a lot of hassle" to "oh, it's going to take some work just to get back to the quality I had with rdoc." And that psychology will prevent people from switching, even if it turns out not to be that much work (for example, if it could largely be automated).
Thanks for the pointer too @see, I will check it out. And thanks for pushing the state of Ruby documentation tools forward.
John
from yard.
Related Issues (20)
- yard gems results in [error]: The file `./docs/yard_plugin.rb' could not be loaded: HOT 8
- Question: Would you like to add some hactoberfest labels? HOT 1
- yard doc/undocumented will list wrapper namespaces (Possibly intractable) HOT 1
- Nasty problem upgrading to 0.9.28
- Question: No support for `private attr_*` syntax? HOT 1
- Rack::Server has removed in Rack 3.0 and the server will not start HOT 1
- Question: parse docstring for classes defined with `@!parse` directive? HOT 2
- Documentation at rubydoc.info - some gems do not have documentation HOT 1
- documenting a metaprogrammed superclass HOT 1
- @!method directive with indented method docstring: parser fails to recognize parameter names HOT 1
- Struct subclasses using block form do not get treated like structs HOT 2
- Running `yard docs --tag owner` fails to generate on classes with comments HOT 3
- Change webrick version spec from `~> 1.7.0` to `~> 1.7` HOT 3
- yard server returns `No such file or directory @ rb_file_s_stat` HOT 1
- Custom layout - ArgumentError: No such template for default/fulldoc/html HOT 3
- Issues with rubydoc.info HOT 1
- Error starting server: nil port HOT 2
- Display table of contents for class/modules
- Strange behavior in parsing private methods
- Documentation of the anonymous block forwarding HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from yard.