All the Frontend services should be documented with jsdoc.

Showtim3 commented 4 years ago

This starter issue is currently on hold because we do not have the capacity to support new contributors working on it.

We aim to document all the files listed below.

Each of the below-listed files should have a file overview signifying the purpose of the file, and each function should have its meaning, arguments and return statement documented with the help of jsdoc decorators like @fileoverview, @param, @return.

You can go through these services to get some reference:

graph-input-rules.service.ts
exploration-html-formatter.service.ts
graph-utils.service.ts
alerts.service.ts
playthrough-issues.service.ts

Deducing variable's significance and the meaning from the code: Try and execute the code by running a dev server locally, and log the variable type (you can use typeof for this) and try to find out the purpose of the variable(what's the variable storing, what is it being used for, what would break if we remove the variable?). To figure out how to execute the code, grep to see what methods call the function, and add console logs to ensure that the code is being executed when you perform the corresponding action in the UI. (As a sanity check, you might also want to ensure that the suspected variable type is consistent with any TypeScript types that are already provided.)

Overview of the function: Finding or deducing the overview or the purpose of the function can be sometimes a bit tricky, some general advice can be to think--

why is this function even required, what does it helps us achieve. Try to think from the perspective of the person who created the function and try to mimic the thought process of the original author.
Look at the callers of the function, see all the places where this function is being called at and try to get a better understanding of the function.
If you are unable to understand the purpose of the function, feel free to reach out to your mentor(always happy to help).

Please go through this doc for a deeper context.

Please don't include types in the JSDoc, use the TypeScript annotations for that.

PR's for reference: #8773

To be assigned to a file or for any queries, comment on the thread and tag @nithusha21.

The listed services file below needs to be documented:

[ ] admin-config-tab-backend-api.service.ts
[ ] admin-data.service.ts
[ ] admin-router.service.ts @anumehaagrawal
[ ] admin-task-manager.service.ts @larakhdavies
[ ] alerts.service.ts
[ ] angular-name.service.ts @parulpriyedarshani
[ ] answer-classification.service.ts
[ ] answer-groups-cache.service.ts
[ ] assets-backend-api.service.ts
[ ] audio-pFlayer.service.ts
[ ] audio-preloader.service.ts
[ ] audio-translation-language.service.ts @kaylahardie
[ ] audio-translation-manager.service.ts
[ ] autogenerated-audio-player.service.ts @BlakeHan01
[ ] autoplayed-videos.service.ts @darkpsychic
[ ] autosave-info-modals.service.ts
[ ] background-mask.service.ts
[ ] base-undo-redo.service.ts
[ ] browser-checker.service.ts
[ ] change-list.service.ts
[ ] changes-in-human-readable-form.service.ts
[ ] classroom-backend-api.service.ts @ReshuKumari
[ ] code-normalizer.service.ts
[ ] collection-creation-backend-api.service.ts
[ ] collection-creation.service.ts
[ ] collection-editor-state.service.ts
[ ] collection-linearizer.service.ts
[ ] collection-rights-backend-api.service.ts
[ ] collection-update.service.ts
[ ] collection-validation.service.ts
[ ] compare-versions.service.ts
[ ] compute-graph.service.ts
[ ] concept-card-backend-api.service.ts
[ ] construct-translation-ids.service.ts @BlakeHan01
[ ] context.service.ts
[ ] contribution-and-review.service.ts @lelouchB
[ ] contribution-opportunities-backend-api.service.ts
[ ] contribution-opportunities.service.ts
[ ] creator-dashboard-backend-api.service.ts
[ ] csrf-token.service.ts
[ ] current-interaction.service.ts
[ ] date-time-format.service.ts @linnhallonqvist
[ ] debouncer.service.ts
[ ] debug-info-tracker.service.ts
[ ] device-info.service.ts
[ ] document-attribute-customization.service.ts
[ ] editability.service.ts
[ ] editable-collection-backend-api.service.ts
[ ] editable-exploration-backend-api.service.ts
[ ] editable-question-backend-api.service.ts
[ ] editable-skill-backend-api.service.ts
[ ] editable-story-backend-api.service.ts
[ ] editable-topic-backend-api.service.ts
[ ] editor-first-time-events.service.ts
[ ] email-dashboard-data.service.ts
[ ] exploration-automatic-text-to-speech.service.ts
[ ] exploration-category.service.ts
[ ] exploration-correctness-feedback.service.ts
[ ] exploration-creation.service.ts
[ ] exploration-data.service.ts
[ ] exploration-diff.service.ts
[ ] exploration-embed-button.service.ts
[ ] exploration-engine.service.ts
[ ] exploration-features-backend-api.service.ts
[ ] exploration-features.service.ts @parulpriyedarshani
[ ] exploration-html-formatter.service.ts
[ ] exploration-init-state-name.service.ts
[ ] exploration-language-code.service.ts
[ ] exploration-objective.service.ts
[ ] exploration-param-changes.service.ts
[ ] exploration-param-specs.service.ts
[ ] exploration-player-state.service.ts
[ ] exploration-property.service.ts
[ ] exploration-recommendations.service.ts
[ ] exploration-rights.service.ts
[ ] exploration-save.service.ts
[ ] exploration-states.service.ts
[ ] exploration-summary-backend-api.service.ts
[ ] exploration-tags.service.ts @shrutisatish00
[ ] exploration-title.service.ts
[ ] exploration-warnings.service.ts
[ ] expression-evaluator.service.ts
[ ] expression-interpolation.service.ts
[ ] expression-parser.service.ts
[ ] expression-syntax-tree.service.ts
[ ] expression-type-parser.service.ts
[ ] extension-tag-assembler.service.ts
[ ] extract-image-filenames-from-state.service.ts
[ ] fatigue-detection.service.ts
[ ] focus-manager.service.ts
[ ] generate-content-id.service.ts
[ ] graph-data.service.ts
[ ] graph-layout.service.ts
[ ] guest-collection-progress.service.ts
[ ] hint-and-solution-modal.service.ts
[ ] hints-and-solution-manager.service.ts
[ ] html-escaper.service.ts @tianqi-wu
[ ] id-generation.service.ts
[ ] image-preloader.service.ts
[ ] image-upload-helper.service.ts
[ ] improvement-modal.service.ts
[ ] improvement-task.service.ts
[ ] improvements-display.service.ts
[ ] improvements.service.ts
[ ] interaction-details-cache.service.ts
[ ] language-util.service.ts
[ ] learner-action-render.service.ts
[ ] learner-answer-details-backend-api.service.ts
[ ] learner-answer-details-data.service.ts
[ ] learner-answer-info.service.ts
[ ] learner-dashboard-backend-api.service.ts
[ ] learner-dashboard-ids-backend-api.service.ts
[ ] learner-params.service.ts
[ ] learner-playlist.service.ts
[ ] learner-view-rating.service.ts
[ ] local-storage.service.ts
[ ] logger.service.ts @remigourdon
[ ] messenger.service.ts @remigourdon
[ ] meta-tag-customization.service.ts
[ ] navigation.service.ts
[ ] nested-directives-recursion-timeout-prevention.service.ts
[ ] number-attempts.service.ts @gp201
[ ] page-title.service.ts
[ ] parameter-metadata.service.ts
[ ] player-correctness-feedback-enabled.service.ts
[ ] player-position.service.ts @tianqi-wu
[ ] player-transcript.service.ts
[ ] playthrough-issues-backend-api.service.ts
[ ] playthrough-issues.service.ts
[ ] playthrough.service.ts
[ ] prediction-algorithm-registry.service.ts
[ ] pretest-question-backend-api.service.ts
[ ] promo-bar.service.ts
[ ] question-backend-api.service.ts
[ ] question-creation.service.ts
[ ] question-player-engine.service.ts
[ ] question-player-state.service.ts
[ ] question-suggestion.service.ts
[ ] question-undo-redo.service.ts
[ ] question-update.service.ts
[ ] questions-list.service.ts
[ ] rating-computation.service.ts
[ ] read-only-collection-backend-api.service.ts
[ ] read-only-exploration-backend-api.service.ts
[ ] refresher-exploration-confirmation-modal.service.ts
[ ] request-interceptor.service.ts
[ ] responses.service.ts
[ ] review-test-backend-api.service.ts
[ ] review-test-engine.service.ts
[ ] router.service.ts
[ ] rte-helper.service.ts
[ ] schema-default-value.service.ts
[ ] schema-undefined-last-element.service.ts
[ ] search-explorations-backend-api.service.ts
[ ] search.service.ts
[ ] sidebar-status.service.ts
[ ] site-analytics.service.ts
[ ] skill-creation.service.ts
[ ] skill-editor-routing.service.ts
[ ] skill-editor-state.service.ts
[ ] skill-mastery-backend-api.service.ts
[ ] skill-rights-backend-api.service.ts
[ ] skill-update.service.ts
[ ] solution-validity.service.ts
[ ] solution-verification.service.ts
[ ] speech-synthesis-chunker.service.ts
[ ] state-classifier-mapping.service.ts
[ ] state-content.service.ts
[ ] state-customization-args.service.ts
[ ] state-editor.service.ts
[ ] state-hints.service.ts
[ ] state-improvement-suggestion.service.ts @bobbychen1999
[ ] state-interaction-id.service.ts
[ ] state-name.service.ts
[ ] state-param-changes.service.ts
[ ] state-property.service.ts
[ ] state-recorded-voiceovers.service.ts
[ ] state-rules-stats.service.ts
[ ] state-solicit-answer-details.service.ts
[ ] state-solution.service.ts
[ ] state-top-answers-stats-backend-api.service.ts
[ ] state-top-answers-stats.service.ts
[ ] state-tutorial-first-time.service.ts @akeeoaobh
[ ] state-written-translations.service.ts
[ ] stats-reporting.service.ts
[ ] story-creation.service.ts
[ ] story-editor-state.service.ts @pengcheng95
[ ] story-update.service.ts
[ ] story-viewer-backend-api.service.ts
[ ] subtopic-viewer-backend-api.service.ts
[ ] suggestion-modal-for-creator-view.service.ts
[ ] suggestion-modal-for-exploration-editor.service.ts
[ ] suggestion-modal-for-exploration-player.service.ts
[ ] suggestion-modal-for-learner-dashboard.service.ts
[ ] suggestion-modal.service.ts
[ ] thread-data.service.ts
[ ] thread-status-display.service.ts
[ ] topic-creation.service.ts
[ ] topic-editor-routing.service.ts
[ ] topic-editor-state.service.ts
[ ] topic-rights-backend-api.service.ts
[ ] topic-update.service.ts
[ ] topic-viewer-backend-api.service.ts
[ ] topics-and-skills-dashboard-backend-api.service.ts
[ ] training-data-editor-panel.service.ts
[ ] training-data.service.ts @felicityzhao99
[ ] training-modal.service.ts @varuncj02
[ ] translate-text.service.ts
[ ] translation-file-hash-loader.service.ts
[ ] translation-language.service.ts
[ ] translation-status.service.ts
[ ] translation-tab-active-content-id.service.ts
[ ] translation-tab-active-mode.service.ts
[ ] undo-redo.service.ts
[ ] url-interpolation.service.ts @qinghaoyang
[ ] url.service.ts @tianqi-wu
[ ] user-email-preferences.service.ts @felicityzhao99
[ ] user-exploration-permissions.service.ts
[ ] user.service.ts
[ ] utils.service.ts @rriyaldhi
[ ] validators.service.ts
[ ] version-tree.service.ts
[ ] voiceover-recording.service.ts
[ ] window-dimensions.service.ts @asafprivman
[ ] window-ref.service.ts @larakhdavies

Note: For a guide on how to access Oppia's webpages, see this.

felicityzhao99 commented 4 years ago

Heyy @bansalnitish Can I take "user-email-preferences.service.ts" and "training-data.services.ts"? Hopefully, it will help me better understand the code and then make more contributions to other topics:)

Showtim3 commented 4 years ago

Hey @felicityzhao99 , I have assigned you both.

felicityzhao99 commented 4 years ago

Hey @felicityzhao99 , I have assigned you both.

Cool thanks:)

bansalnitish commented 4 years ago

Any updates @felicityzhao99? Please let us know if you need any help :).

felicityzhao99 commented 4 years ago

Hi Nitish, Yea, actually I sent you my confusion several days ago. I really need your help, could you please check at gitter? I resend it in private!

Thanks, Felicity

On Wed, Feb 26, 2020 at 10:52 PM Nitish Bansal notifications@github.com wrote:

Any updates @felicityzhao99 https://github.com/felicityzhao99? Please let us know if you need any help :).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/oppia/oppia/issues/8668?email_source=notifications&email_token=AHVYNBHO46PXTMBT4Q7RPXLRE5PMDA5CNFSM4KWYSXQKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOENDFP2A#issuecomment-591812584, or unsubscribe https://github.com/notifications/unsubscribe-auth/AHVYNBBQPXXRO3THNPTPQKLRE5PMDANCNFSM4KWYSXQA .

Showtim3 commented 4 years ago

@felicityzhao99 I'd suggest that you can post your query here only, that'd be better.

bansalnitish commented 4 years ago

Yeah, could you please post your query here @felicityzhao99?

I'm not that active on gitter. Also, more folks will be able to help you out here.

felicityzhao99 commented 4 years ago

Hi @Showtim3 @bansalnitish sorry for the late reply! I have already finished my tasks and the thing is I can't commit my code:

Can anyone help with this error? Thanks in advance!

bansalnitish commented 4 years ago

Hey @felicityzhao99, Could you please merge your branch with updated develop?

Let me know if it still doesn't work.

felicityzhao99 commented 4 years ago

Hi @bansalnitish, the thing is I can't make commit locally to my feature branch. So if I'm right, you want me to do git merge feature-branch before successfully committed?

Also, I'm guessing it's yaml problem? or do I need to refork?

Thanks so much for your help!

bansalnitish commented 4 years ago

Could you do git status and check that changes are just related to the files that you've changed?

No, you don't need to refork.

felicityzhao99 commented 4 years ago

Hi @bansalnitish

Yea, I think it's the right file that I wanna commit. Not sure what's happened.

Also, one more question, do you know where is the related front-end page of training-data.service.ts? I check the path: core/templates/dev/head/pages/exploration-editor-page/editor-tab/training-panel/training-data.service.ts and think it's in the exploration-editor-page and click the editor tab but what's the training panel? Also why the editor tab always got an introduction error?

Sorry for these bunch of questions, it actually confused me a lot. I'm looking forward to seeing your message and fix them tomorrow. Good night:)

felicityzhao99 commented 4 years ago

Hi @Showtim3, could you please tell me where the training-data.service.ts been used?

felicityzhao99 commented 4 years ago

@Showtim3 @bansalnitish PTAL Also wanna ask how to set you all as the PR assignee and what kind of label do I need to mention?

lelouchB commented 4 years ago

Hey @Showtim3 I want to work on
contribution-and-review.service.ts

Showtim3 commented 4 years ago

@lelouchB Assigned you.

akeeoaobh commented 4 years ago

Hey, may I work on state-tutorial-first-time.service.ts?

Showtim3 commented 4 years ago

@lelouchB Hey, how's the work going? Do you need help with something? Feel free to ping here for any kind of assistance.

@akeeoaobh Assigned you!

lelouchB commented 4 years ago

@Showtim3 I am still working on it Had to leave it in between bcoz of the lockdown and stuff but will be working on it now Thanks 😊 I will surely ask you if I get stuck

Showtim3 commented 4 years ago

@lelouchB Okay, thanks for the reply. No Worries, take your time and stay safe.

shrutisatish00 commented 4 years ago

hey @Showtim3 , would like to work on exploration-tags.service.ts. Thanks!

Showtim3 commented 4 years ago

Hey @shrutisatish00 assigned you.

MonicaDJohnson commented 4 years ago

I would like to work on this particular issue, if at all possible. I am a beginner; I'm not sure where to start, but I want to help out!

feorgie commented 4 years ago

Like Monica above I'm also a beginner and keen to help out!

Showtim3 commented 4 years ago

Hey @MonicaDJohnson , go through the issue description, there's a doc explaining what's this issue about, that will give you some context on how you are supposed to work on this issue. Then pick a file from the above list and I'll assign that to you.

Showtim3 commented 4 years ago

Hey @feorgie you can start from here.

Showtim3 commented 4 years ago

Hey @lelouchB What's up?

rriyaldhi commented 4 years ago

hi, can I be assigned to utils.service.ts? thanks in advance

Showtim3 commented 4 years ago

@rriyaldhi Done.

kaylahardie commented 3 years ago

Hey @Showtim3 I'm currently looking at the audio-translation-language.service.ts file and am trying to add the type for the _languageInExploration property as well as add overall documentation for the file

Showtim3 commented 3 years ago

Hey @kaylahardie That sounds great. Let me know if you need any help. Assigned you the file.

varuncj02 commented 3 years ago

Hey @Showtim3 can I work on training-modal.service.ts . I am new to the open source community so would like to start from there

Showtim3 commented 3 years ago

Yeah sure @varuncj02 Assigned you.

aks681 commented 3 years ago

Seems this was closed accidentally when a PR was merged, reopening.

nairnikhil12 commented 3 years ago

Hey @Showtim3, can I work on autoplayed-videos.service.ts

Showtim3 commented 3 years ago

Assigned you @darkpsychic

tianqi-wu commented 3 years ago

Hey @Showtim3, Can I do html-escaper.service.ts, url.service.ts, and player-position.service.ts? Thanks a lot!

Showtim3 commented 3 years ago

Oh @tianqi-wu You want to take 3 serivces at a time? :P Ok assigned you all three.

pengcheng95 commented 3 years ago

Hey @Showtim3, can i work on story-editor-state.service.ts. Thanks!

ankita240796 commented 3 years ago

Hey @Showtim3, can i work on story-editor-state.service.ts. Thanks!

Sure @pengcheng95, I have assigned you the file. Thanks!

ReshuKumari commented 3 years ago

@Showtim3 can I work on classroom-backend-api.service.ts

Showtim3 commented 3 years ago

@ReshuKumari Assigned you.

bobbychen1999 commented 3 years ago

@Showtim3 Can I work on state-improvement-suggestion.service.ts?

bobbychen1999 commented 3 years ago

@Showtim3 Can I work on state-interaction-id.service.ts? I do not know why, but I am having problem finding state-improvement-suggestion.service.ts

remigourdon commented 3 years ago

Hi @Showtim3 !

New aspiring contributor here :). I had a look at some of the files and I would like to know if I can work on:

logger.service.ts
messenger.service.ts

Showtim3 commented 3 years ago

Hey @remigourdon Assigned you, also sorry for the delay.

anumehaagrawal commented 3 years ago

@Showtim3 can you assign me the admin-router.service.ts file here?

Showtim3 commented 3 years ago

Hey @anumehaagrawal Done.

linnhallonqvist commented 3 years ago

Hi! I would like to start contributing to the Oppia project as a part of an open source course I take at university. @Showtim3 could you assign me to the date-time-format.service.ts file?

Showtim3 commented 3 years ago

Hey @linnhallonqvist Done(sorry for the delay).

oppia / oppia

All the Frontend services should be documented with jsdoc. #8668