Add documentation on writing codebase docs.

 






 

 


  Review Request #7896
  —
  Created Jan. 18, 2016 and submitted 

 


















 

  

   Information

  





 
 

  chipx86
 









 
 

  Review Board
 









 
 

  release-2.5.x
 









 
 

  
 









 
 

  
 






 




 

  

   Reviewers

  





 
 

  reviewboard
 









 
 

  
 






 








 





  


 
 

  
This covers how to document source code in our projects. It goes over
the Python and JavaScript documentation syntax we are or will be using,
the format we use for listing arguments and return values and such, and
other guidelines we have for the documentation.

The JavaScript doc guidelines don't actually match what we have today.
Instead, it's more of a proposal for what we should do going forward.
The reason is that, in researching options for generating codebase docs,
I've found that what we're doing isn't going to be sufficient. So this
covers a new set of standards that we can fairly easily start moving to
as we go.

 








  


 
 

  
Built the docs and read through them. Checked all links and references,

and checked for spelling errors.

 







 









 





  








 






 
 
 

  

   

    

     
    

    
    
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
    

   

   

    
     

      Description
      From
      Last Updated
     

    
    



     

      
       
       
Too many blank lines here.

      		
      
       daviddavid
      
      
       
      
     




     

      
       
       
These should be capitalized, no?

      		
      
       daviddavid
      
      
       
      
     


    
   

  

 







 






  

 








 














 





 

  

   




reviewbot




   

   





  

 



 

  


   

   

    
 
reviewbot


    
   


  

  

  



    




  1. 
 
    
  
    
   
    Tool: Pyflakes
Ignored Files:
    docs/codebase/docs/writing-codebase-docs.rst
    docs/codebase/index.rst



Tool: PEP8 Style Checker
Ignored Files:
    docs/codebase/docs/writing-codebase-docs.rst
    docs/codebase/index.rst


    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 















  2. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 




  

 
















 





 

  

   




david




   

   









  

 



 

  


   

   

    
 
david


    
   


  

  

  



    




  1. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/codebase/docs/writing-codebase-docs.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



    
    Too many blank lines here.
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 




  3. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    4. 




  

 
















 





 

  

   




david




   

   







  

 



 

  


   

   

    
 
david


    
   


  

  

  



    




  1. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       docs/codebase/docs/writing-codebase-docs.rst
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

     
     
    

     
     
    

     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



    
    These should be capitalized, no?
    
  
    
 
    

 
    
  


    
 
    
 
      

  


    1. 
 
 
      
 
      
  
 
      
 
      
  
      So I was thinking so initially, and was using/recommending that. Then I dug in while I was writing these docs, looking at what others do and what's appropriate.
      

      According to Mozilla's docs, these are the actual fundamental types, under the hood. You can't use them directly, but they're what's probably most appropriate. Other doc systems recommend using these when dealing with such primitives. Things like String and Object are implementations of those primitives. So, I went with these, to help distinguish them. I'm not married to this, though.
      
 
      

      2. 



    2. 
 
 
      
 
      
  
 
      
 
      
  
      That sounds to me like "under the hood" means "in the SpiderMonkey implementation". The ECMAScript specification uses capital letters for these types.
      
 
      

      3. 



    3. 
 
 
      
 
      
  
 
      
 
      
  
      Maybe, honestly wasn't sure. Just went and dug into a bunch of the more popular JS libraries and doc solutions. Here's what I found.
      

      YUIDoc shows examples using String, Boolean, etc. jQuery uses this format for their docs (sorta -- they make up a lot of types like "htmlString" and "Selector" and "Integer" such, so I think it's more about creating consistency there and not about truly referencing JS types).
      

      JSDoc, ESDoc, Sphinx, and documentation.js show examples using string, boolean, etc. pdf.js, Angular, React, and Lodash use this format. This seems to be the most common form out there amongst libs that document types.
      

      Plenty of libraries don't even list types in their docs, but that's not ideal.
      
 
      

      4. 



    4. 
 
 
      
 
      
  
 
      
 
      
  
      Well, my vote is for using what the ECMAScript spec uses :P
      
 
      

      5. 



    5. 
 
 
      
 
      
  
 
      
 
      
  
      Yeah I don't know, maybe. I'm not sure that what ECMAScript is doing is really the same thing. The same docs that reference String and Object also reference Null, Undefined, List, and some other things that aren't actually types in JavaScript. I think that's more spec-level definitions and not documentation definitions. ECMAScript even documents that string, boolean, etc. are the primitive types behind String, Boolean, etc. (which they are, so of course that makes sense).
      

      Google also recommends string, boolean, etc. JSDoc, apparently, won't even allow Boolean and String, and is considered the gold standard in doc formats for JavaScript. The more I look, the more I see the trend swinging to these types. So I think that's really the right way to go.
      
 
      

      6. 



    6. 
 
 
      
 
      
  
 
      
 
      
  
      Very well.
      
 
      

      7. 


 
    


    

 
    

    3. 




  3. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    4. 




  

 
















 



 

  

   




chipx86




   

   

  

 



 

  


   

   

    
 Review request changed

    
   


  

  

  







  

   

    Status:
   

   


    Completed

   

  




  

   

    Change Summary:
   

   

    
Pushed to release-2.5.x (ee855e7)