#yardoc — Public Fediverse posts

@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

https://docs.python.org/3/library/pydoc.html

@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

https://docs.python.org/3/library/pydoc.html

@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

https://docs.python.org/3/library/pydoc.html

@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

https://docs.python.org/3/library/pydoc.html

@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

https://docs.python.org/3/library/pydoc.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.

https://github.com/mastodon/mastodon/issues/29141

#MastodonDev #ruby #rails

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.

https://github.com/mastodon/mastodon/issues/29141

#MastodonDev #ruby #rails

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.

https://github.com/mastodon/mastodon/issues/29141

#MastodonDev #ruby #rails

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.

https://github.com/mastodon/mastodon/issues/29141

#MastodonDev #ruby #rails

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.

https://github.com/mastodon/mastodon/issues/29141

#MastodonDev #ruby #rails

I'm thinking about asking on the #Mastodon issue tracker about introducing inline documentation using #yardoc or #rdoc to public functions on modules and classes.

Was there any issue, discussion or call for this already?

#MastodonDev

I'm thinking about asking on the #Mastodon issue tracker about introducing inline documentation using #yardoc or #rdoc to public functions on modules and classes.

Was there any issue, discussion or call for this already?

#MastodonDev

I'm thinking about asking on the #Mastodon issue tracker about introducing inline documentation using #yardoc or #rdoc to public functions on modules and classes.

Was there any issue, discussion or call for this already?

#MastodonDev

I'm thinking about asking on the #Mastodon issue tracker about introducing inline documentation using #yardoc or #rdoc to public functions on modules and classes.

Was there any issue, discussion or call for this already?

#MastodonDev

I'm thinking about asking on the #Mastodon issue tracker about introducing inline documentation using #yardoc or #rdoc to public functions on modules and classes.

Was there any issue, discussion or call for this already?

#MastodonDev

RBS/RBI are great for *type checking* and validating code, but not for *documenting*. End-developers, such as myself, still need to lookup a gem's API documentation and figure out what a certain method accepts or returns. YARD solves that problem nicely, and annotating your APIs with YARD tags helps you mentally double-check your API.
#yardoc #YARD

RBS/RBI are great for *type checking* and validating code, but not for *documenting*. End-developers, such as myself, still need to lookup a gem's API documentation and figure out what a certain method accepts or returns. YARD solves that problem nicely, and annotating your APIs with YARD tags helps you mentally double-check your API.
#yardoc #YARD

RBS/RBI are great for *type checking* and validating code, but not for *documenting*. End-developers, such as myself, still need to lookup a gem's API documentation and figure out what a certain method accepts or returns. YARD solves that problem nicely, and annotating your APIs with YARD tags helps you mentally double-check your API.
#yardoc #YARD

RBS/RBI are great for *type checking* and validating code, but not for *documenting*. End-developers, such as myself, still need to lookup a gem's API documentation and figure out what a certain method accepts or returns. YARD solves that problem nicely, and annotating your APIs with YARD tags helps you mentally double-check your API.
#yardoc #YARD

RBS/RBI are great for *type checking* and validating code, but not for *documenting*. End-developers, such as myself, still need to lookup a gem's API documentation and figure out what a certain method accepts or returns. YARD solves that problem nicely, and annotating your APIs with YARD tags helps you mentally double-check your API.
#yardoc #YARD

@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

@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

@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

@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

@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

TIL https://gemdocs.org/ is a viable alternative to https://rubydoc.info (currently down). Also supports YARD docs and seems fairly fast.
#ruby #docs #yard #yardoc

TIL https://gemdocs.org/ is a viable alternative to https://rubydoc.info (currently down). Also supports YARD docs and seems fairly fast.
#ruby #docs #yard #yardoc

TIL https://gemdocs.org/ is a viable alternative to https://rubydoc.info (currently down). Also supports YARD docs and seems fairly fast.
#ruby #docs #yard #yardoc

TIL https://gemdocs.org/ is a viable alternative to https://rubydoc.info (currently down). Also supports YARD docs and seems fairly fast.
#ruby #docs #yard #yardoc

TIL https://gemdocs.org/ is a viable alternative to https://rubydoc.info (currently down). Also supports YARD docs and seems fairly fast.
#ruby #docs #yard #yardoc

Anyone here able to give a good overview of the differences in capabilities between YARD and RBS beyond the fact that the two store types in different places? I know both have type checkers but I’m curious to know if RBS would have the same ability to document types as YARD or if one can cover more situations than the other. #yardoc #ruby #rbs

Anyone here able to give a good overview of the differences in capabilities between YARD and RBS beyond the fact that the two store types in different places? I know both have type checkers but I’m curious to know if RBS would have the same ability to document types as YARD or if one can cover more situations than the other. #yardoc #ruby #rbs

Anyone here able to give a good overview of the differences in capabilities between YARD and RBS beyond the fact that the two store types in different places? I know both have type checkers but I’m curious to know if RBS would have the same ability to document types as YARD or if one can cover more situations than the other. #yardoc #ruby #rbs

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.

#ruby #yardoc #documentation #softwaredevelopment

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.

#ruby #yardoc #documentation #softwaredevelopment

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.

#ruby #yardoc #documentation #softwaredevelopment

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

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

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