Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs badge to README #404

Merged
merged 1 commit into from Oct 10, 2014

Conversation

@rrrene
Copy link
Contributor

commented Oct 7, 2014

Hi there,

I would like to propose a docs badge for Elixir projects. Since Elixir declared documentation to be a "first class citizen" and I already had created Inch for Ruby, I decided to try to implement "inline-docs linting" for Elixir as well.

This is what it would look like: Inline docs (click to view status page)

The idea is to show to potential contributors that a lib/package is documented and to inspire people starting with Elixir to follow suit. The badge links to Inch CI, a project that tries to raise the visibility of inline-docs to encourage aspiring programmers to document their code. Inch CI is still relatively new (4 months old), but it is already relatively succesful (badges used by 300+ Ruby projects including Guard, Haml, Pry, ROM, and Sass).

Please understand this not as "I built something, now use it!" but rather a call for discussion. I made a functioning prototype implementation of this (as the badge shows), but I want to emphazise the "prototype" part. There is no well-thought-out UI or workflow for you to add your own projects (yet) and the evaluation criteria are up for discussion as well as any other design choices I made.

@ALL: What do you think? Let's talk!

@rrrene rrrene referenced this pull request Oct 7, 2014
@chrismccord

This comment has been minimized.

Copy link
Member

commented Oct 10, 2014

Very cool! Elixir makes documentation first class and this fact shouldn't be missed. Let's see how this goes!

chrismccord added a commit that referenced this pull request Oct 10, 2014
Merge pull request #404 from rrrene/add-docs-badge
Add docs badge to README

@chrismccord chrismccord merged commit 648fa69 into phoenixframework:master Oct 10, 2014

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details
@josevalim

This comment has been minimized.

Copy link
Member

commented Oct 10, 2014

@rrrene that's nice! Quick question: do you skip the module completely if it is marked with @moduledoc false?

@rrrene

This comment has been minimized.

Copy link
Contributor Author

commented Oct 10, 2014

@chrismccord Yay!

@josevalim It does and I was actually thinking about changing that. But this is a good example of why I wanted to start a discussion with you guys:

defmodule Phoenix.Naming do
  @moduledoc false

  @doc """
  Extracts the resource name from an alias
  """
  def resource_name(alias, suffix \\ nil) do
    alias
    |> Module.split()
    |> List.last()
    |> remove_suffix(suffix)
    |> Phoenix.Naming.underscore()
  end
end

In the above made-up example: Should it be transitive and hide the complete Phoenix.Naming module from evaluation or should it skip Phoenix.Naming itself but evaluate its public functions, like Phoenix.Naming.resource_name?

@josevalim

This comment has been minimized.

Copy link
Member

commented Oct 10, 2014

@rrrene it should skip the module completely. Documentation is for third party consumption and that way Phoenix is saying that the module is not available to the public.

@josevalim

This comment has been minimized.

Copy link
Member

commented Oct 10, 2014

In other words, please don't change, the current behaviour is great.

@josevalim

This comment has been minimized.

Copy link
Member

commented Oct 10, 2014

Btw, you should also skip the modules which are an implementation of a protocol. Similar to how we do here: https://github.com/elixir-lang/ex_doc/blob/master/lib/ex_doc/retriever.ex#L205

Here are other functions you should skip too: https://github.com/elixir-lang/ex_doc/blob/master/lib/ex_doc/retriever.ex#L119-L137

@rrrene

This comment has been minimized.

Copy link
Contributor Author

commented Oct 10, 2014

Very cool, thanks for pointing those out!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.