@serge many of the projects we use in Python, like #Flask, are documented using #Sphinx, which can be configured to automatically generate API documentation from Python source code:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
This is (similar to the #yardoc and #rdoc situation) backwards compatible with #pydoc, though much more expressive due to the machine-readable format for defining parameters, return values and potential exceptions:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
I think inline #documentation is an important tool to making software readable. It makes software maintainable, encourages future development and makes it easier to join the project as a developer.
This is why I advocate for #mastodon to start encouraging inline documentation with #yardoc, requiring it for any new PRs and serving this API documentation on joinmastodon.org.
@katafrakt depends on what you mean by excellent YARD docs. I would recommend:
* command_kit (https://rubydoc.info/gems/command_kit)
* spidr (https://rubydoc.info/gems/spidr)
* Ronin gems (https://ronin-rb.dev/docs/#api)
* most of my gems since I always use YARD and try to get >80% doc coverage.
#YARD #yardoc
Anyone got any good recommendations for getting started with improving #yardoc documentation within an existing project?
Been trying to see what people recommend online but most of what I have found has been more tutorials on YARD itself than how to actually develop a system for monitoring and increasing the level of documentation within a product using a systematic approach.
If I'm understanding the issue you're encountering, the `[attach]` macro clause is supposed to do this. However, I've never gotten it to work properly.
My issue with this has been slightly different; I want the *declaration* of the class method to have its own docco, describing what it does, but _also_ have the `[attach]` functionality to provide a boilerplate so each use of it documents the attributes it's declaring.
#tuby #YARD #yardoc
How do YARDoc users document calls to DSL methods that are called within another block in a class, and are defined in another gem? Example:
```
class MyClass < OtherGem::DSL
setup do
define_some_method :foo, type: String
end
end
```
Do I really have to manually type out @!method macros for each defined reader/writer or is there some way to do this using @!macro?
#ruby #yard #yardoc
CSDUMMI
postmodern
Grant Willcox
Grant Willcox
GenghisKen Coar