Mailing-List: contact dev-help@hc.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "HttpComponents Project" <dev@hc.apache.org>
Date: Wed, 27 Jun 2012 18:45:44 +0000 (UTC)
From: "miles zarathustra (JIRA)" <jira@apache.org>
To: dev@hc.apache.org
Message-ID: <2063362521.63223.1340822744031.JavaMail.jiratomcat@issues-vm>
In-Reply-To: <1947356321.25250.1338527362898.JavaMail.jiratomcat@issues-vm>
Subject: [jira] [Commented] (HTTPCLIENT-1201) provide basic documentation in
 an obvious place
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


    [ https://issues.apache.org/jira/browse/HTTPCLIENT-1201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13402455#comment-13402455 ] 

miles zarathustra commented on HTTPCLIENT-1201:
-----------------------------------------------

If you want to keep the try statements where they are, it would help to explain the rationale for doing so.  I could try to add an explanation, but I would probably get it wrong.

I guess you're assuming the entire code fragment happens inside a try/catch block?  It just seems weird to me to publish a fragment that won't compile without some sort of explanation.  You leave the reader guessing why it is written that way, and if the reader is like me, they'll guess wrong.  I think the example is still too inscrutable.  

I will defer to your greater plan on this topic.


Thanks,
  -= miles =-

                
> provide basic documentation in an obvious place
> -----------------------------------------------
>
>                 Key: HTTPCLIENT-1201
>                 URL: https://issues.apache.org/jira/browse/HTTPCLIENT-1201
>             Project: HttpComponents HttpClient
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions: 4.2 Final
>            Reporter: miles zarathustra
>            Priority: Minor
>             Fix For: 4.2.1
>
>         Attachments: GetPostExample.java, site-1.patch, site.patch
>
>
> The only documentation obviously linked from the main HttpClient page is the "tutorial."  This "tutorial" talks about a lot of esoteric arcane junk I don't care about, but gives no clue on how to send parameters via a basic post.  For that, I have to go here: 
> http://wiki.apache.org/HttpComponents/QuickStart
> It's very difficult to find, and it's a lot easier to google examples that don't work.  I wound up trying 4 different purported solutions before I found this one that works. If you look around the web you'll notice that people generally find the httpclient documentation frustrating.  I have colleagues who argue that it would be easier to just write the post logic from scratch than figure out how the silly apache stuff works, and it's difficult for me to contradict them.
> It would be SO easy to improve the situation by making links to already available examples of the basic operations in an obvious place.
> The FAQ that explains some things about WHY the posts work in the totally non-intuitive way that they do would be nice also.
> Thanks.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

        
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org