ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2025-06-13 04:38:15 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[API] Incorporate newer feedback

Browse Source
This commit is contained in:
Victor Woeltjen
2015-08-17 09:49:34 -07:00
parent 12760b63b9
commit 4d4fe7f626
1 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/src/design/proposals/APIRedesign.md
View File

@ -26,6 +26,7 @@ A good API:
* Rewards doing things "the right way." * Rewards doing things "the right way."
* Saves development effort. * Saves development effort.
* Is powerful enough to support a broad range of applications. * Is powerful enough to support a broad range of applications.
* Lends itself to good documentation.
These characteristics can sometimes be at odds with each other, or These characteristics can sometimes be at odds with each other, or
with other concerns. These should typically be viewed as participants with other concerns. These should typically be viewed as participants
@ -65,6 +66,10 @@ useful, powerful interfaces.
This feedback comes from interns who worked closely with This feedback comes from interns who worked closely with
Open MCT Web as their primary task over the Summer of 2015. Open MCT Web as their primary task over the Summer of 2015.
### Developer Intern 1
Worked on bug fixes in the platform and a plugin for search.
* Initially, it was confusing that many things in files that are in * Initially, it was confusing that many things in files that are in
very different locations in the code base refer to each other. very different locations in the code base refer to each other.
* Perhaps explain more the organization strategy behind the * Perhaps explain more the organization strategy behind the
@ -95,6 +100,21 @@ Open MCT Web as their primary task over the Summer of 2015.
"Telemetry" and the "Telemetry Service"? There are many "Telemetry" and the "Telemetry Service"? There are many
"Telemetry Thing"s which seem related, but in an unclear way. "Telemetry Thing"s which seem related, but in an unclear way.
### Developer Intern 2
Worked on platform bug fixes and mobile support.
* No guide for the UI and front end for the HTML/CSS part of Open MCT Web.
Not sure if this is applicable or needed for developers, however would
be helpful to any front end development
* Found it difficult to follow the plot controller & subplot
functions/features, such as zooming.
* If the developer guide could have for references to which files or
functions are key for gestures, browse navigation, etc it would be
helpful for future developers as a place to start looking. I found
it occasionally difficult to find which files or functions I wanted
at first.
## Plugin Developer Feedback ## Plugin Developer Feedback
This feedback comes from developers who have worked on plugins for This feedback comes from developers who have worked on plugins for
@ -269,12 +289,17 @@ The following attributes of the current API are undesirable:
[ ] It is difficult to tell "where things are" in the code base. [ ] It is difficult to tell "where things are" in the code base.
[ ] It is difficult to see how objects are passed around at run-time. [ ] It is difficult to see how objects are passed around at run-time.
[ ] It is difficult to trace flow of control generally.
[ ] Multiple interfaces for related concepts (e.g. telemetry) is confusing. [ ] Multiple interfaces for related concepts (e.g. telemetry) is confusing.
[ ] API documentation is missing or not well-formatted for use. [ ] API documentation is missing or not well-formatted for use.
[ ] High-level separation of concerns is not made clear. [ ] High-level separation of concerns is not made clear.
[ ] Interface depth of telemetry API is excessive (esp. `TelemetrySeries`) [ ] Interface depth of telemetry API is excessive (esp. `TelemetrySeries`)
[ ] Capabilities as a concept lack clarity. [ ] Capabilities as a concept lack clarity.
[ ] Too many interfaces and concepts to learn. [ ] Too many interfaces and concepts to learn.
[ ] Exposing third-party APIs (e.g. Angular's) increases the learning curve.
[ ] Want more examples, easier-to-use documentation.
[ ] UI-relevant features (HTML, CSS) under-documented
[ ] Good MVC for views of domain objects not enforced (e.g. plots)
## Positive Features ## Positive Features
@ -282,6 +307,8 @@ It is desirable to retain the following features in an API redesign:
[ ] Creating new features and implementing them additively is well-supported. [ ] Creating new features and implementing them additively is well-supported.
[ ] Easy to add/remove features which involve multiple concerns. [ ] Easy to add/remove features which involve multiple concerns.
[ ] Features can be self-contained.
[ ] Declarative syntax makes it easy to tell what's in use.
## Requirements ## Requirements