[jira] [Commented] (SQOOP-1680) DOC: Create an API doc for the Sqoop repository.

["Gwen Shapira (JIRA)" <ji...@apache.org>]

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

Gwen Shapira commented on SQOOP-1680:
-------------------------------------

I'd rather not duplicate docs, and the repository also have JavaDocs.
I thought JavaDocs are the standard method for documenting internal APIs. 

Using my usual example:
Kafka has an excellent ConfigDef library used internally. The JavaDocs are great and ensured new devs use this correctly, but there's no other documentation, since this is internal. Producer and Consumer are external and have real documentation which we maintain, with specific examples on how to use them, best practices, etc.

>  DOC: Create an API doc for the Sqoop repository.
> -------------------------------------------------
>
>                 Key: SQOOP-1680
>                 URL: https://issues.apache.org/jira/browse/SQOOP-1680
>             Project: Sqoop
>          Issue Type: Bug
>            Reporter: Veena Basavaraj
>            Assignee: Veena Basavaraj
>             Fix For: 1.99.5
>
>
> Having a good doc for repository will encourage us to create better code going forward to support other types of repository.
> Even the repo upgrade can be its own clean api
> Well we have connector developer guide that details the responsibilities. 
> I have similar thoughts for the exec engine and repository.
> You many ask why? If we think ourselves as external developers we will take less shortcuts and make our code mode extensible and clean is my thought.
> for instance
> Should the create link api enforce the unique constraint on name or the database table should. these are not documented anywhere clearly for someone trying to add a new repo and the recommended practices are nice to have



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)