Add better documention for 'jar.with_artifact()', including an example

Review Request #192 — Created April 9, 2014 and submitted

areitz
pants
pants-reviews
jsirois, lahosken
Add better documention for 'jar.with_artifact()', including an example

There is a known issue with HTML output for the ":param" docs for .with_artifact(), that will be fixed in a subsequent branch from Larry.


JS
  1. 
      
  2. This is probably backwards.  Artifact owns this data so should probably host the docs, and JarDependency just forwards to it.
    1. I think Andy moved the doc so the BUILD dictionary generator could "see" it.
      
      If this is too ugly, we could probably move the ugliness to the BUILD dictionary generator, throwing in some special logic for jar_dependency.
    2. Right comment - wrong spot :/
      
      Aha - that makes sense.  In the long run it would definitely be nice to pydoc for pydoc sake and have it just work when generating site docs, but I'm fine with getting there bit by bit.
    3. The problem that I saw is that there are two Artifact objects -- one in jar_dependency.py, and another in artifact.py. The latter already appears in the BUILD dictionary, so I thought it would be confusing if the former appeared, especially since you cannot actually depend on it in a BUILD file. (jar_dependency.Artifact is for internal use only).
  3. 
      
LA
  1. 
      
  2. src/python/pants/docs/3rdparty_jvm.rst (Diff revision 1)
     
     
    Asking, not telling: is different classifiers the most common way this happens? This wording makes me think so.
    
    If that's true, great.
    
    But if that makes you say "actually, the most common case is ..." then maybe change "This can occur with" to "One tricky way this can occur is with"
    1. Aha - that makes sense.  In the long run it would definitely be nice to pydoc for pydoc sake and have it just work when generating site docs, but I'm fine with getting there bit by bit.
  3. 
      
JS
  1. Ship It!
  2. 
      
AR
LA
  1. yay for also clarifying the doc-gen process
  2. 
      
AR
Review request changed

Status: Closed (submitted)

Loading...